ruby-trello-wgibbs 0.4.3

data/README.md

@@ -0,0 +1,37 @@
+# Ruby Trello API
+
+[![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).
+
+Trello is an awesome tool for organization. Not just aimed at developers, but everybody.
+Seriously, [check it out](http://www.trello.com/).
+
+## Installation
+
+```
+# gem install ruby-trello
+```
+
+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
+
+A special thanks goes out to [Ben Biddington](https://github.com/ben-biddington) who has contributed a significant amount
+of refactoring and functionality to be deserving of a beer and this special thanks.
+
+## Contributing
+
+Several ways you can contribute. Documentation, code, tests, feature requests, bug reports.
+
+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.

data/lib/trello/action.rb

@@ -0,0 +1,46 @@
+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,
+      :readonly => [ :id, :type, :data, :date, :member_creator_id ]
+    validates_presence_of :id, :type, :date, :member_creator_id
+
+    class << self
+      # Locate a specific action and return a new Action object.
+      def find(id)
+        super(:actions, id)
+      end
+    end
+
+    # Update the attributes of an action
+    #
+    # Supply a hash of string keyed data retrieved from the Trello API representing
+    # an Action.
+    def update_fields(fields)
+      attributes[:id]                = fields['id']
+      attributes[:type]              = fields['type']
+      attributes[:data]              = fields['data']
+      attributes[:date]              = Time.iso8601(fields['date'])
+      attributes[:member_creator_id] = fields['idMemberCreator']
+      self
+    end
+
+    # Returns the board this action occurred on.
+    def 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)
+    end
+
+    # Returns the list the action occurred on.
+    def 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
+  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

@@ -0,0 +1,114 @@
+require 'securerandom'
+require "oauth"
+
+module Trello
+  module Authorization
+
+    AuthPolicy = Class.new
+
+    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
+        end
+      end
+    end
+
+    class Clock
+      def self.timestamp; Time.now.to_i; end
+    end
+
+    class Nonce
+      def self.next
+        SecureRandom.hex()
+      end
+    end
+
+    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, :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
+        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)
+        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 = {})
+          self.token ||= OAuththCredential.new
+
+          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.sign!(request, OAuth::Token.new(token.key, token.secret))
+
+          request['authorization']
+        end
+      end
+    end
+  end
+end

data/lib/trello/basic_data.rb

@@ -0,0 +1,84 @@
+require 'trello/string'
+
+module Trello
+  class BasicData
+    include ActiveModel::Validations
+    include ActiveModel::Dirty
+    include ActiveModel::Serializers::JSON
+
+    class << self
+      def find(path, id)
+        Client.get("/#{path}/#{id}").json_into(self)
+      end
+    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
+          @attributes ||= names.inject({}) { |hash,k| hash.merge(k.to_sym => nil) }
+        end
+
+        names.each do |key|
+          define_method(:"#{key}") { @attributes[key] }
+
+          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
+
+    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)
+    end
+
+    def update_fields(fields)
+      raise NotImplementedError, "#{self.class} does not implement update_fields."
+    end
+
+    # Refresh the contents of our object.
+    def refresh!
+      self.class.find(id)
+    end
+
+    # Two objects are equal if their _id_ methods are equal.
+    def ==(other)
+      id == other.id
+    end
+  end
+end

data/lib/trello/board.rb

@@ -0,0 +1,95 @@
+module Trello
+  class Board < BasicData
+    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
+
+    class << self
+      # Finds a board.
+      def find(id)
+        super(:boards, id)
+      end
+
+      def create(fields)
+        new('name'   => fields[:name],
+            'desc'   => fields[:description],
+            'closed' => fields[:closed] || false).save
+      end
+    end
+
+    def save
+      return update! if id
+
+      fields = { :name => name }
+      fields.merge!(:desc => description) if description
+      fields.merge!(:idOrganization => organization_id) if organization_id
+
+      Client.post("/boards", fields).json_into(self)
+    end
+
+    def update!
+      fail "Cannot save new instance." unless self.id
+
+      @previously_changed = changes
+      @changed_attributes.clear
+
+      Client.put("/boards/#{self.id}/", {
+        :name        => @name,
+        :description => @description,
+        :closed      => @closed
+      }).json_into(self)
+    end
+
+    def update_fields(fields)
+      attributes[:id]              = fields['id']              if fields['id']
+      attributes[:name]            = fields['name']            if fields['name']
+      attributes[:description]     = fields['desc']            if fields['desc']
+      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]
+    end
+
+    def has_lists?
+      lists.size > 0
+    end
+
+    # Return all the cards on this board.
+    #
+    # 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
+    many :cards, :filter => :open
+
+    # Returns all the lists on this board.
+    #
+    # 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
+    many :lists, :filter => :open
+
+    # Returns an array of members who are associated with this board.
+    #
+    # 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
+    many :members, :filter => :all
+
+    # Returns a reference to the organization this board belongs to.
+    one :organization, :using => :organization_id
+
+    # :nodoc:
+    def request_prefix
+      "/boards/#{id}"
+    end
+  end
+end

data/lib/trello/card.rb

@@ -0,0 +1,162 @@
+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, :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
+
+    class << self
+      # Find a specific card by its id.
+      def find(id)
+        super(:cards, id)
+      end
+
+      # Create a new card and save it on Trello.
+      def create(options)
+        new('name'   => options[:name],
+            'idList' => options[:list_id],
+            'desc'   => options[:description]).save
+      end
+    end
+
+    # Update the fields of a card.
+    #
+    # Supply a hash of string keyed data retrieved from the Trello API representing
+    # a card.
+    def update_fields(fields)
+      attributes[:id]          = fields['id']
+      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']
+      attributes[:member_ids]  = fields['idMembers']
+      attributes[:list_id]     = fields['idList']
+      self
+    end
+
+    # Returns a reference to the board this card is part of.
+    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
+    many :checklists, :filter => :all
+
+    # Returns a reference to the list this card is currently in.
+    one :list, :using => :list_id
+
+    # Returns a list of members who are assigned to this card.
+    def members
+      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.
+    def save
+      # If we have an id, just update our fields.
+      return update! if id
+
+      Client.post("/cards", {
+        :name   => name,
+        :desc   => description,
+        :idList => list_id
+      }).json_into(self)
+    end
+
+    # Update an existing record.
+    # Warning, this updates all fields using values already in memory. If
+    # an external resource has updated these fields, you should refresh!
+    # this object before making your changes, and before updating the record.
+    def update!
+      @previously_changed = changes
+      @changed_attributes.clear
+
+      Client.put("/cards/#{id}", {
+        :name      => name,
+        :desc      => description,
+        :due       => due && due.utc.iso8601,
+        :closed    => closed,
+        :idList    => list_id,
+        :idBoard   => board_id,
+        :idMembers => member_ids
+      })
+    end
+
+    # Is the record valid?
+    def valid?
+      name && list_id
+    end
+
+    # Add a comment with the supplied text.
+    def add_comment(text)
+      Client.post("/cards/#{id}/actions/comments", :text => text)
+    end
+
+    # Add a checklist to this card
+    def add_checklist(checklist)
+      Client.post("/cards/#{id}/checklists", {
+        :value => checklist.id
+      })
+    end
+
+    # Add a member to this card
+    def add_member(member)
+      Client.post("/cards/#{id}/members", {
+        :value => member.id
+      })
+    end
+
+    # Remove a member from this card
+    def remove_member(member)
+      Client.delete("/cards/#{id}/members/#{member.id}")
+    end
+
+    # Move this card to the given list
+    def move_to_list(list)
+      Client.put("/cards/#{id}/idList", {
+        :value => list.id
+      })
+    end
+
+    # Retrieve a list of labels
+    def labels
+      labels = Client.get("/cards/#{id}/labels").json_into(Label)
+      MultiAssociation.new(self, labels).proxy
+    end
+
+    # Add a label
+    def add_label(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)
+      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
+
+    # :nodoc:
+    def request_prefix
+      "/cards/#{id}"
+    end
+
+  end
+end

data/lib/trello/checklist.rb

@@ -0,0 +1,82 @@
+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,
+      :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.
+      def find(id)
+        super(:checklists, id)
+      end
+
+      def create(options)
+        new('name'       => options[:name],
+            'idBoard'    => options[:board_id]).save
+      end
+    end
+
+    # Update the fields of a checklist.
+    #
+    # Supply a hash of string keyed data retrieved from the Trello API representing
+    # a checklist.
+    def update_fields(fields)
+      attributes[:id]          = fields['id']
+      attributes[:name]        = fields['name']
+      attributes[:description] = fields['desc']
+      attributes[:closed]      = fields['closed']
+      attributes[:url]         = fields['url']
+      attributes[:check_items] = fields['checkItems']
+      attributes[:board_id]    = fields['idBoard']
+      attributes[:member_ids]  = fields['idMembers']
+      self
+    end
+
+    # Check if the checklist is currently active.
+    def closed?
+      closed
+    end
+
+    # Save a record.
+    def save
+      return update! if id
+
+      Client.post("/checklists", {
+        :name    => name,
+        :idBoard => board_id
+      }).json_into(self)
+    end
+
+    def update!
+      Client.put("/checklists/#{id}", { :name => name }).json_into(self)
+    end
+
+    # Return a list of items on the checklist.
+    def items
+      check_items.map do |item_fields|
+        Item.new(item_fields)
+      end
+    end
+
+    # Return a reference to the board the checklist is on.
+    one :board, :using => :board_id
+
+    # Return a reference to the list the checklist is on.
+    one :list, :using => :list_id
+
+    # Return a list of members active in this checklist.
+    def members
+      members = member_ids.map do |member_id|
+        Member.find(member_id)
+      end
+      MultiAssociation.new(self, members).proxy
+    end
+
+    # Add an item to the checklist
+    def add_item(name)
+      Client.post("/checklists/#{id}/checkItems", { :name => name })
+    end
+  end
+end