ruby-trello 0.4.0 → 0.4.1

data/README.md

@@ -1,6 +1,6 @@
 # Ruby Trello API
 
-[![Build Status](https://secure.travis-ci.org/jeremytregunna/ruby-trello.png)](http://travis-ci.org/jeremytregunna/ruby-trello)
+[![Build Status](https://secure.travis-ci.org/jeremytregunna/ruby-trello.png)](http://travis-ci.org/jeremytregunna/ruby-trello) [![Dependency Status](https://gemnasium.com/jeremytregunna/ruby-trello.png)](https://gemnasium.com/jeremytregunna/ruby-trello.png)
 
 This library implements the [Trello](http://www.trello.com/) [API](http://trello.com/api).
 
@@ -13,7 +13,8 @@ Seriously, [check it out](http://www.trello.com/).
 # gem install ruby-trello
 ```
 
-Full Disclosure: This library is not complete, but it does function enough to be useful.
+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).
 
 ## Special thanks
 

data/lib/trello/action.rb

@@ -1,7 +1,8 @@
 module Trello
   # Action represents some event that occurred. For instance, when a card is created.
   class Action < BasicData
-    register_attributes :id, :type, :data, :date, :member_creator_id
+    register_attributes :id, :type, :data, :date, :member_creator_id,
+      :readonly => [ :id, :type, :data, :date, :member_creator_id ]
     validates_presence_of :id, :type, :date, :member_creator_id
 
     class << self
@@ -19,7 +20,7 @@ module Trello
       attributes[:id]                = fields['id']
       attributes[:type]              = fields['type']
       attributes[:data]              = fields['data']
-      attributes[:date]              = fields['date']
+      attributes[:date]              = Time.iso8601(fields['date'])
       attributes[:member_creator_id] = fields['idMemberCreator']
       self
     end
@@ -40,8 +41,6 @@ module Trello
     end
 
     # Returns the member who created the action.
-    def member_creator
-      Member.find(member_creator_id)
-    end
+    one :member_creator, :via => Member, :using => :member_creator_id
   end
 end

data/lib/trello/association.rb

@@ -0,0 +1,11 @@
+module Trello
+  class Association
+    attr_reader :owner, :target, :options, :proxy
+
+    def initialize(owner, target)
+      @owner  = owner
+      @target = target
+      @options = {}
+    end
+  end
+end

data/lib/trello/association_proxy.rb

@@ -0,0 +1,42 @@
+require 'active_support/core_ext'
+
+module Trello
+  class AssociationProxy
+    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 initialize(association)
+      @association = association
+      Array(association.options[:extend]).each { |ext| proxy_extend(ext) }
+    end
+
+    def proxy_assocation
+      @association
+    end
+
+    def method_missing(method, *args, &block)
+      if target.respond_to? method
+        target.send(method, *args, &block)
+      else
+        super
+      end
+    end
+
+    def ===(other)
+      other === target
+    end
+
+    def to_ary
+      proxy_assocation.dup
+    end
+    alias_method :to_a, :to_ary
+
+    def <<(*records)
+      proxy_assocation.concat(records) && self
+    end
+  end
+end

data/lib/trello/authorization.rb

@@ -1,4 +1,5 @@
 require 'securerandom'
+require "oauth"
 
 module Trello
   module Authorization
@@ -32,9 +33,28 @@ module Trello
 
     OAuthCredential = Struct.new "OAuthCredential", :key, :secret
 
+    # Handles the OAuth connectivity to Trello.
+    #
+    # For 2-legged OAuth, do the following:
+    #
+    #    OAuthPolicy.consumer_credential = OAuthCredential.new "public_key", "secret"
+    #    OAuthPolicy.token               = OAuthCredential.new "token_key", nil
+    #
+    # For 3-legged OAuth, do the following:
+    #
+    #    OAuthPolicy.consumer_credential = OAuthCredential.new "public_key", "secret"
+    #    OAuthPolicy.return_url          = "http://your.site.com/path/to/receive/post"
+    #    OAuthPolicy.callback            = Proc.new do |request_token|
+    #      DB.save(request_token.key, request_token.secret)
+    #      redirect_to request_token.authorize_url
+    #    end
+    #
+    # Then, recreate the request token given the request token key and secret you saved earlier,
+    # and the consumer, and pass that RequestToken instance the #get_access_token method, and
+    # store that in OAuthPolicy.token as a OAuthCredential.
     class OAuthPolicy
       class << self
-        attr_accessor :consumer_credential, :token
+        attr_accessor :consumer_credential, :token, :return_url, :callback
 
         def authorize(request)
           unless consumer_credential
@@ -42,26 +62,40 @@ module Trello
             fail "The consumer_credential has not been supplied."
           end
 
-          request.headers = {"Authorization" => get_auth_header(request.uri, :get)}
-          request
+          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
 
         private
 
-        def get_auth_header(url, verb)
-          require "oauth"
-
-          self.token ||= OAuthCredential.new
+        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
 
-          consumer = OAuth::Consumer.new(
+        def consumer(options = {})
+          @consumer ||= OAuth::Consumer.new(
             consumer_credential.key,
             consumer_credential.secret,
-            {
-              :scheme      => :header,
-              :scope       => 'read,write,account',
-              :http_method => verb
-            }
+            consumer_params(options)
           )
+        end
+
+        def get_auth_header(url, verb, options = {})
+          self.token ||= OAuththCredential.new
 
           request = Net::HTTP::Get.new Addressable::URI.parse(url).to_s
 

data/lib/trello/basic_data.rb

@@ -13,6 +13,9 @@ module Trello
     end
 
     def self.register_attributes(*names)
+      options = { :readonly => [] }
+      options.merge!(names.pop) if names.last.kind_of? Hash
+
       # Defines the attribute getter and setters.
       class_eval do
         define_method :attributes do
@@ -22,16 +25,43 @@ module Trello
         names.each do |key|
           define_method(:"#{key}") { @attributes[key] }
 
-          define_method :"#{key}=" do |val|
-            send(:"#{key}_will_change!") unless val == @attributes[key]
-            @attributes[key] = val
+          unless options[:readonly].include?(key.to_sym)
+            define_method :"#{key}=" do |val|
+              send(:"#{key}_will_change!") unless val == @attributes[key]
+              @attributes[key] = val
+            end
           end
         end
+
         define_attribute_methods names
       end
     end
 
-    register_attributes :id
+    def self.one(name, opts = {})
+      class_eval do
+        define_method(:"#{name}") do |*args|
+          options = opts.dup
+          klass   = options.delete(:via) || Trello.const_get(name.to_s.camelize)
+          ident   = options.delete(:using) || :id
+          klass.find(self.send(ident))
+        end
+      end
+    end
+
+    def self.many(name, opts = {})
+      class_eval do
+        define_method(:"#{name}") do |*args|
+          options   = opts.dup
+          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}", options).json_into(klass)
+          MultiAssociation.new(self, resources).proxy
+        end
+      end
+    end
+
+    register_attributes :id, :readonly => [ :id ]
 
     def initialize(fields = {})
       update_fields(fields)

data/lib/trello/board.rb

@@ -1,8 +1,10 @@
 module Trello
-
   class Board < BasicData
-    register_attributes :id, :name, :description, :url, :organization_id
+    register_attributes :id, :name, :description, :closed, :url, :organization_id, :prefs,
+      :readonly => [ :id, :url, :organization_id, :prefs ]
     validates_presence_of :id, :name
+    validates_length_of   :name,        :in      => 1..16384
+    validates_length_of   :description, :maximum => 16384
 
     include HasActions
 
@@ -49,49 +51,41 @@ module Trello
       attributes[:closed]          = fields['closed']          if fields.has_key?('closed')
       attributes[:url]             = fields['url']             if fields['url']
       attributes[:organization_id] = fields['idOrganization']  if fields['idOrganization']
-
+      attributes[:prefs]           = fields['prefs'] || {}
       self
     end
 
     def closed?
-      @attributes[:closed]
+      attributes[:closed]
+    end
+
+    def has_lists?
+      lists.size > 0
     end
 
     # Return all the cards on this board.
     #
-    # The options hash may have a filter key which can have its value set as any
+    # This method, when called, can take a hash table with a filter key containing any
     # of the following values:
     #    :filter => [ :none, :open, :closed, :all ] # default :open
-    def cards(options = { :filter => :open })
-      Client.get("/boards/#{id}/cards").json_into(Card)
-    end
-
-    def has_lists?
-      lists.size > 0
-    end
+    many :cards, :filter => :open
 
     # Returns all the lists on this board.
     #
-    # The options hash may have a filter key which can have its value set as any
+    # This method, when called, can take a hash table with a filter key containing any
     # of the following values:
     #    :filter => [ :none, :open, :closed, :all ] # default :open
-    def lists(options = { :filter => :open })
-      Client.get("/boards/#{id}/lists", options).json_into(List)
-    end
+    many :lists, :filter => :open
 
     # Returns an array of members who are associated with this board.
     #
-    # The options hash may have a filter key which can have its value set as any
+    # This method, when called, can take a hash table with a filter key containing any
     # of the following values:
     #    :filter => [ :none, :normal, :owners, :all ] # default :all
-    def members(options = { :filter => :all })
-      Client.get("/boards/#{id}/members", options).json_into(Member)
-    end
+    many :members, :filter => :all
 
     # Returns a reference to the organization this board belongs to.
-    def organization
-      Organization.find(organization_id)
-    end
+    one :organization, :using => :organization_id
 
     # :nodoc:
     def request_prefix

data/lib/trello/card.rb

@@ -1,8 +1,11 @@
 module Trello
   # A Card is a container that can house checklists and comments; it resides inside a List.
   class Card < BasicData
-    register_attributes :id, :short_id, :name, :description, :closed, :url, :board_id, :member_ids, :list_id
+    register_attributes :id, :short_id, :name, :description, :due, :closed, :url, :board_id, :member_ids, :list_id,
+      :readonly => [ :id, :short_id, :url, :board_id, :member_ids ]
     validates_presence_of :id, :name, :list_id
+    validates_length_of   :name,        :in => 1..16384
+    validates_length_of   :description, :in => 0..16384
 
     include HasActions
 
@@ -29,6 +32,7 @@ module Trello
       attributes[:short_id]    = fields['idShort']
       attributes[:name]        = fields['name']
       attributes[:description] = fields['desc']
+      attributes[:due]         = Time.iso8601(fields['due']) rescue nil
       attributes[:closed]      = fields['closed']
       attributes[:url]         = fields['url']
       attributes[:board_id]    = fields['idBoard']
@@ -38,29 +42,24 @@ module Trello
     end
 
     # Returns a reference to the board this card is part of.
-    def board
-      Board.find(board_id)
-    end
+    one :board, :using => :board_id
 
     # Returns a list of checklists associated with the card.
     #
     # The options hash may have a filter key which can have its value set as any
     # of the following values:
     #    :filter => [ :none, :all ] # default :all
-    def checklists(options = { :filter => :all })
-      Client.get("/cards/#{id}/checklists", options).json_into(Checklist)
-    end
+    many :checklists, :filter => :all
 
     # Returns a reference to the list this card is currently in.
-    def list
-      List.find(list_id)
-    end
+    one :list, :using => :list_id
 
     # Returns a list of members who are assigned to this card.
     def members
-      member_ids.map do |member_id|
+      members = member_ids.map do |member_id|
         Client.get("/members/#{member_id}").json_into(Member)
       end
+      MultiAssociation.new(self, members).proxy
     end
 
     # Saves a record.
@@ -83,14 +82,15 @@ module Trello
       @previously_changed = changes
       @changed_attributes.clear
 
-      Client.put("/cards/#{@id}", {
+      Client.put("/cards/#{id}", {
         :name      => name,
         :desc      => description,
+        :due       => due && due.utc.iso8601,
         :closed    => closed,
         :idList    => list_id,
         :idBoard   => board_id,
         :idMembers => member_ids
-      }).json_into(self)
+      })
     end
 
     # Is the record valid?
@@ -112,13 +112,19 @@ module Trello
 
     # Add a label
     def add_label(colour)
-      return logger.warn "The label colour '#{colour}' does not exist." unless %w{green yellow orange red purple blue}.include? colour
+      unless %w{green yellow orange red purple blue}.include? colour
+        errors.add(:label, "colour '#{colour}' does not exist")
+        return Trello.logger.warn "The label colour '#{colour}' does not exist."
+      end
       Client.post("/cards/#{id}/labels", { :value => colour })
     end
 
     # Remove a label
     def remove_label(colour)
-      return logger.warn "The label colour '#{colour}' does not exist." unless %w{green yellow orange red purple blue}.include? colour
+      unless %w{green yellow orange red purple blue}.include? colour
+        errors.add(:label, "colour '#{colour}' does not exist")
+        return Trello.logger.warn "The label colour '#{colour}' does not exist." unless %w{green yellow orange red purple blue}.include? colour
+      end
       Client.delete("/cards/#{id}/labels/#{colour}")
     end
 

data/lib/trello/checklist.rb

@@ -1,8 +1,10 @@
 module Trello
   # A Checklist holds items which are like a "task" list. Checklists are linked to a card.
   class Checklist < BasicData
-    register_attributes :id, :name, :description, :closed, :url, :check_items, :board_id, :list_id, :member_ids
+    register_attributes :id, :name, :description, :closed, :url, :check_items, :board_id, :list_id, :member_ids,
+      :readonly => [ :id, :description, :closed, :url, :check_items, :board_id, :list_id, :member_ids ]
     validates_presence_of :id, :board_id, :list_id
+    validates_length_of   :name, :in => 1..16384
 
     class << self
       # Locate a specific checklist by its id.
@@ -42,13 +44,13 @@ module Trello
       return update! if id
 
       Client.post("/checklists", {
-        :name => @name,
-        :idBoard => @board_id
+        :name    => name,
+        :idBoard => board_id
       }).json_into(self)
     end
 
     def update!
-      Client.put("/checklists", { :name => @name }).json_into(self)
+      Client.put("/checklists", { :name => name }).json_into(self)
     end
 
     # Return a list of items on the checklist.
@@ -59,20 +61,17 @@ module Trello
     end
 
     # Return a reference to the board the checklist is on.
-    def board
-      Board.find(board_id)
-    end
+    one :board, :using => :board_id
 
     # Return a reference to the list the checklist is on.
-    def list
-      List.find(list_id)
-    end
+    one :list, :using => :list_id
 
     # Return a list of members active in this checklist.
     def members
-      member_ids.map do |member_id|
+      members = member_ids.map do |member_id|
         Member.find(member_id)
       end
+      MultiAssociation.new(self, members).proxy
     end
 
     # Add an item to the checklist

data/lib/trello/client.rb

@@ -30,6 +30,8 @@ module Trello
         request = Request.new name, uri, {}, body
         response = TInternet.execute AuthPolicy.authorize(request)
 
+        return '' unless response
+
         if response.code.to_i == 401 && response.body =~ /expired token/
           Trello.logger.error("[401 #{name.to_s.upcase} #{uri}]: Your access token has expired.")
           raise InvalidAccessToken, response.body

data/lib/trello/has_actions.rb

@@ -2,7 +2,8 @@ module Trello
   module HasActions
     # Returns a list of the actions associated with this object.
     def actions(options = {})
-      Client.get("#{request_prefix}/actions", { :filter => :all }.merge(options)).json_into(Action)
+      actions = Client.get("#{request_prefix}/actions", { :filter => :all }.merge(options)).json_into(Action)
+      MultiAssociation.new(self, actions).proxy
     end
   end
 end

data/lib/trello/item.rb

@@ -1,7 +1,7 @@
 module Trello
   # An Item is a basic task that can be checked off and marked as completed.
   class Item < BasicData
-    register_attributes :id, :name, :type
+    register_attributes :id, :name, :type, :readonly => [ :id, :name, :type ]
     validates_presence_of :id, :type
 
     # Updates the fields of an item.

data/lib/trello/item_state.rb

@@ -1,7 +1,7 @@
 module Trello
   # Represents the state of an item.
   class ItemState < BasicData
-    register_attributes :id, :state, :item_id
+    register_attributes :id, :state, :item_id, :readonly => [ :id, :state, :item_id ]
     validates_presence_of :id, :item_id
 
     # Update the fields of an item state.

data/lib/trello/list.rb

@@ -1,8 +1,9 @@
 module Trello
   # A List is a container which holds cards. Lists are items on a board.
   class List < BasicData
-    register_attributes :id, :name, :closed, :board_id
+    register_attributes :id, :name, :closed, :board_id, :readonly => [ :id, :board_id ]
     validates_presence_of :id, :name, :board_id
+    validates_length_of   :name, :in => 1..16384
 
     include HasActions
 
@@ -34,16 +35,16 @@ module Trello
       return update! if id
 
       Client.post("/lists", {
-        :name    => @name,
-        :closed  => @closed || false,
-        :idBoard => @board_id
+        :name    => name,
+        :closed  => closed || false,
+        :idBoard => board_id
       }).json_into(self)
     end
 
     def update!
       Client.put("/lists", {
-        :name   => @name,
-        :closed => @closed
+        :name   => name,
+        :closed => closed
       }).json_into(self)
     end
 
@@ -53,18 +54,14 @@ module Trello
     end
 
     # Return the board the list is connected to.
-    def board
-      Board.find(board_id)
-    end
+    one :board, :using => :board_id
 
     # Returns all the cards on this list.
     #
     # The options hash may have a filter key which can have its value set as any
     # of the following values:
     #    :filter => [ :none, :open, :closed, :all ] # default :open
-    def cards(options = { :filter => :open })
-      Client.get("/lists/#{id}/cards", options).json_into(Card)
-    end
+    many :cards, :filter => :open
 
     # :nodoc:
     def request_prefix

data/lib/trello/member.rb

@@ -1,8 +1,10 @@
 module Trello
   # A Member is a user of the Trello service.
   class Member < BasicData
-    register_attributes :id, :username, :full_name, :avatar_id, :bio, :url
+    register_attributes :id, :username, :full_name, :avatar_id, :bio, :url, :readonly => [ :id, :username, :avatar_id, :url ]
     validates_presence_of :id, :username
+    validates_length_of   :full_name, :minimum => 4
+    validates_length_of   :bio,       :maximum => 16384
 
     include HasActions
 
@@ -41,46 +43,51 @@ module Trello
 
     # Returns a list of the boards a member is a part of.
     #
-    # The options hash may have a filter key which can have its value set as any
+    # This method, when called, can take a hash table with a filter key containing any
     # of the following values:
     #   :filter => [ :none, :members, :organization, :public, :open, :closed, :all ] # default: :all
-    def boards(options = { :filter => :all })
-      Client.get("/members/#{username}/boards", options).json_into(Board)
-    end
+    # i.e.,
+    #    me.boards(:filter => :closed) # retrieves all closed boards
+    many :boards, :filter => :all
 
     # Returns a list of cards the member is assigned to.
     #
-    # The options hash may have a filter key which can have its value set as any
+    # This method, when called, can take a hash table with a filter key containing any
     # of the following values:
     #    :filter => [ :none, :open, :closed, :all ] # default :open
-    def cards(options = { :filter => :open })
-      Client.get("/members/#{username}/cards", options).json_into(Card)
-    end
+    # i.e.,
+    #    me.cards(:filter => :closed) # retrieves all closed cards
+    many :cards, :filter => :open
 
     # Returns a list of the organizations this member is a part of.
     #
-    # The options hash may have a filter key which can have its value set as any
+    # This method, when called, can take a hash table with a filter key containing any
     # of the following values:
     #   :filter => [ :none, :members, :public, :all ] # default: all
-    def organizations(options = { :filter => :all })
-      Client.get("/members/#{username}/organizations", options).json_into(Organization)
-    end
+    # i.e.,
+    #    me.organizations(:filter => :public) # retrieves all public organizations
+    many :organizations, :filter => :all
 
     # Returns a list of notifications for the user
-    def notifications
-      Client.get("/members/#{username}/notifications").json_into(Notification)
-    end
+    many :notifications
 
     def save
       @previously_changed = changes
       @changed_attributes.clear
 
-      # TODO: updating attributes.
+      return update! if id
+    end
+
+    def update!
+      Client.put(request_prefix, {
+        :displayName => full_name,
+        :bio         => bio
+      }).json_into(self)
     end
 
     # :nodoc:
     def request_prefix
-      "/members/#{username}"
+      "/members/#{id}"
     end
   end
 end

data/lib/trello/multi_association.rb

@@ -0,0 +1,10 @@
+module Trello
+  class MultiAssociation < Association
+    delegate :count, :to => :target
+
+    def initialize(owner, target = [])
+      super
+      @proxy = AssociationProxy.new(self)
+    end
+  end
+end