ruby-trello 1.1.3 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 81baf76d9e58785fa9dc51f1d712b882b92db245
-  data.tar.gz: a73d11ce0d6308962b78802fdca44e60d5d84fec
+  metadata.gz: 260b90a4f5cc53cb0c695edb040c75144a24a2f0
+  data.tar.gz: 1b6e24750bb32ae29d798912b43a60e98ece7088
 SHA512:
-  metadata.gz: 9d99de48aaf068f1bd67db5d5f39fe8aa8b0fe04c40285b5775a0409048f75e0d17ddee6fa98a3d14f79b2319dd607feb30e0742fb79c562070463b4d7d3f648
-  data.tar.gz: 62a787fc187af9d034103afd7331bc3f74155750777c07e67aef1838ddb6581af853aef33f7633def4385643b83ba55d4af593aa6b1688a2ea4861366e20deb1
+  metadata.gz: 913d7972b22fce3998ea166fc1dc94c8d4e699ef2f1b2b686fd585fb951b430769b74dbb8d3e2d90bd3e99791da8b5018f15839bbf79a636917e52fbb1d492c6
+  data.tar.gz: f68c3097b8e2c8cf043587b98aa7559b8aeb14c35891bea11de1edab13cf6e04be0adaf48df7dd0db4be4afb17211fd21cc5e865105435c5fd139f1fc6ac18fd

data/README.md

@@ -26,12 +26,14 @@ illustrate that future versions may include ruby 1.9.3+ specific features.
 
 Basic authorization:
 
-1. Get your API keys from [trello.com/app-key](https://trello.com/app-key). 
+1. Get your API keys from [trello.com/app-key](https://trello.com/app-key).
 2. Visit the URL [trello.com/1/authorize], with the following GET parameters:
     - `key`: the API key you got in step 1.
     - `response_type`: "token"
     - `expiration`: "never" if you don't want your token to ever expire. If you leave this blank,
        your generated token will expire after 30 days.
+    - The URL will look like this:
+      `https://trello.com/1/authorize?key=YOURAPIKEY&response_type=token&expiration=never`
 3. You should see a page asking you to authorize your Trello application. Click "allow" and you should see a second page with a long alphanumeric string. This is your member token.
 
 ```ruby

data/lib/trello/action.rb

@@ -1,8 +1,21 @@
 module Trello
   # Action represents some event that occurred. For instance, when a card is created.
+  #
+  # @!attribute [r] id
+  #   @return [String]
+  # @!attribute [r] type
+  #   @return [String]
+  # @!attribute [r] data
+  #   @return [Hash]
+  # @!attribute [r] date
+  #   @return [Datetime]
+  # @!attribute [r] member_creator_id
+  #   @return [String]
+  # @!attribute [r] member_participant
+  #   @return [Object]
   class Action < BasicData
     register_attributes :id, :type, :data, :date, :member_creator_id, :member_participant,
-      :readonly => [ :id, :type, :data, :date, :member_creator_id, :member_participant ]
+      readonly: [ :id, :type, :data, :date, :member_creator_id, :member_participant ]
     validates_presence_of :id, :type, :date, :member_creator_id
 
     class << self
@@ -13,9 +26,8 @@ module Trello
 
       def search(query, opts={})
         response = client.get("/search/", { query: query }.merge(opts))
-        formatted_response = JSON.parse(response).except("options").inject({}) do |res, key|
-          res.merge!({ key.first => key.last.jsoned_into("Trello::#{key.first.singularize.capitalize}".constantize) })
-          res
+        JSON.parse(response).except("options").inject({}) do |res, key|
+          res.merge({ key.first => key.last.jsoned_into("Trello::#{key.first.singularize.capitalize}".constantize) })
         end
       end
     end
@@ -50,6 +62,6 @@ module Trello
     end
 
     # Returns the member who created the action.
-    one :member_creator, :via => Member, :path => :members, :using => :member_creator_id
+    one :member_creator, via: Member, path: :members, using: :member_creator_id
   end
 end

data/lib/trello/attachment.rb

@@ -1,5 +1,20 @@
 module Trello
   # A file or url that is linked to a Trello card
+  #
+  # @!attribute id
+  #   @return [String]
+  # @!attribute name
+  #   @return [String]
+  # @!attribute url
+  #   @return [String]
+  # @!attribute bytes
+  #   @return [Fixnum]
+  # @!attribute date
+  #   @return [Datetime]
+  # @!attribute is_upload
+  #   @return [Boolean]
+  # @!attribute mime_type
+  #   @return [String]
   class Attachment < BasicData
     register_attributes :name, :id, :url, :bytes, :member_id, :date, :is_upload, :mime_type
     # Update the fields of an attachment.

data/lib/trello/authorization.rb

@@ -31,7 +31,7 @@ module Trello
       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 }
+        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
@@ -100,8 +100,8 @@ module Trello
           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(:oauth_callback => return_url)
+          consumer(return_url: return_url, callback_method: :postMessage)
+          request_token = consumer.get_request_token(oauth_callback: return_url)
           callback.call request_token
           return nil
         end
@@ -151,12 +151,12 @@ module Trello
 
       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"
+          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
 

data/lib/trello/basic_data.rb

@@ -44,7 +44,7 @@ module Trello
     end
 
     def self.register_attributes(*names)
-      options = { :readonly => [] }
+      options = { readonly: [] }
       options.merge!(names.pop) if names.last.kind_of? Hash
 
       # Defines the attribute getter and setters.
@@ -102,7 +102,7 @@ module Trello
       Trello.client
     end
 
-    register_attributes :id, :readonly => [ :id ]
+    register_attributes :id, readonly: [ :id ]
 
     attr_writer :client
 

data/lib/trello/board.rb

@@ -1,16 +1,40 @@
 module Trello
+
+  # A board on Trello
+  #
+  # @!attribute [r] id
+  #   @return [String]
+  # @!attribute [r] name
+  #   @return [String]
+  # @!attribute [rw] description
+  #   @return [String]
+  # @!attribute [rw] closed
+  #   @return [Boolean]
+  # @!attribute [r] url
+  #   @return [String]
+  # @!attribute [rw] organization_id
+  #   @return [String] A 24-character hex string
+  # @!attribute [r] prefs
+  #   @return [Hash] A 24-character hex string
   class Board < BasicData
-    register_attributes :id, :name, :description, :closed, :url, :organization_id, :prefs,
-      :readonly => [ :id, :url, :prefs ]
+    register_attributes :id, :name, :description, :closed, :starred, :url, :organization_id, :prefs,
+      readonly: [ :id, :url, :prefs ]
     validates_presence_of :id, :name
-    validates_length_of   :name,        :in      => 1..16384
-    validates_length_of   :description, :maximum => 16384
+    validates_length_of   :name,        in: 1..16384
+    validates_length_of   :description, maximum: 16384
 
     include HasActions
 
     class << self
       # Finds a board.
       #
+      # @param [String] id Either the board's short ID (an alphanumeric string,
+      #     found e.g. in the board's URL) or its long ID (a 24-character hex
+      #     string.)
+      # @param [Hash] params
+      #
+      # @raise  [Trello::Board] if a board with the given ID could not be found.
+      #
       # @return [Trello::Board]
       def find(id, params = {})
         client.find(:board, id, params)
@@ -20,8 +44,10 @@ module Trello
         data = {
           'name'   => fields[:name],
           'desc'   => fields[:description],
-          'closed' => fields[:closed] || false }
+          'closed' => fields[:closed] || false,
+          'starred' => fields[:starred] || false }
         data.merge!('idOrganization' => fields[:organization_id]) if fields[:organization_id]
+        data.merge!('prefs' => fields[:prefs]) if fields[:prefs]
         client.create(:board, data)
       end
 
@@ -34,9 +60,10 @@ module Trello
     def save
       return update! if id
 
-      fields = { :name => name }
-      fields.merge!(:desc => description) if description
-      fields.merge!(:idOrganization => organization_id) if organization_id
+      fields = { name: name }
+      fields.merge!(desc: description) if description
+      fields.merge!(idOrganization: organization_id) if organization_id
+      fields.merge!(flat_prefs)
 
       client.post("/boards", fields).json_into(self)
     end
@@ -47,12 +74,16 @@ module Trello
       @previously_changed = changes
       @changed_attributes.clear
 
-      client.put("/boards/#{self.id}/", {
-        :name           => attributes[:name],
-        :description    => attributes[:description],
-        :closed         => attributes[:closed],
-        :idOrganization => attributes[:organization_id]
-      }).json_into(self)
+      fields = {
+        name: attributes[:name],
+        description: attributes[:description],
+        closed: attributes[:closed],
+        starred: attributes[:starred],
+        idOrganization: attributes[:organization_id]
+      }
+      fields.merge!(flat_prefs)
+
+      client.put("/boards/#{self.id}/", fields).json_into(self)
     end
 
     def update_fields(fields)
@@ -60,6 +91,7 @@ module Trello
       attributes[:name]            = fields['name']            if fields['name']
       attributes[:description]     = fields['desc']            if fields['desc']
       attributes[:closed]          = fields['closed']          if fields.has_key?('closed')
+      attributes[:starred]          = fields['starred']          if fields.has_key?('starred')
       attributes[:url]             = fields['url']             if fields['url']
       attributes[:organization_id] = fields['idOrganization']  if fields['idOrganization']
       attributes[:prefs]           = fields['prefs'] || {}
@@ -71,6 +103,11 @@ module Trello
       attributes[:closed]
     end
 
+    # @return [Boolean]
+    def starred?
+      attributes[:starred]
+    end
+    
     # @return [Boolean]
     def has_lists?
       lists.size > 0
@@ -82,29 +119,40 @@ module Trello
       client.get("/boards/#{self.id}/cards/#{card_id}").json_into(Card)
     end
 
+    # Add a member to this Board.
+    #    type => [ :admin, :normal, :observer ]
+    def add_member(member, type = :normal)
+      client.put("/boards/#{self.id}/members/#{member.id}", { type: type })
+    end
+
+    # Remove a member of this Board.
+    def remove_member(member)
+      client.delete("/boards/#{self.id}/members/#{member.id}")
+    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
+    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
+    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
+    many :members, filter: :all
 
     # Returns a reference to the organization this board belongs to.
-    one :organization, :path => :organizations, :using => :organization_id
+    one :organization, path: :organizations, using: :organization_id
 
     def labels
       labels = client.get("/boards/#{id}/labelnames").json_into(LabelName)
@@ -115,5 +163,29 @@ module Trello
     def request_prefix
       "/boards/#{id}"
     end
+
+    private
+
+    # On creation
+    # https://trello.com/docs/api/board/#post-1-boards
+    # - permissionLevel
+    # - voting
+    # - comments
+    # - invitations
+    # - selfJoin
+    # - cardCovers
+    # - background
+    # - cardAging
+    #
+    # On update
+    # https://trello.com/docs/api/board/#put-1-boards-board-id
+    # Same as above plus:
+    # - calendarFeedEnabled
+    def flat_prefs
+      separator = id ? "/" : "_"
+      attributes[:prefs].inject({}) do |hash, (pref, v)|
+        hash.merge("prefs#{separator}#{pref}" => v)
+      end
+    end
   end
 end

data/lib/trello/card.rb

@@ -1,13 +1,48 @@
 module Trello
   # A Card is a container that can house checklists and comments; it resides inside a List.
+  #
+  # @!attribute [r] id
+  #   @return [String]
+  # @!attribute [r] short_id
+  #   @return [Fixnum]
+  # @!attribute [rw] name
+  #   @return [String]
+  # @!attribute [rw] desc
+  #   @return [String]
+  # @!attribute [rw] due
+  #   @return [Datetime]
+  # @!attribute [rw] closed
+  #   @return [Boolean]
+  # @!attribute [r] url
+  #   @return [String]
+  # @!attribute [r] short_url
+  #   @return [String]
+  # @!attribute [rw] board_id
+  #   @return [String] A 24-character hex string
+  # @!attribute [rw] member_ids
+  #   @return [Array<String>] An Array of 24-character hex strings
+  # @!attribute [rw] list_id
+  #   @return [String] A 24-character hex string
+  # @!attribute [rw] pos
+  #   @return [Float]
+  # @!attribute [r] last_activity_date
+  #   @return [Dateime]
+  # @!attribute [rw] card_labels
+  #   @return [Array<Hash>]
+  # @!attribute [rw] cover_image_id
+  #   @return [String] A 24-character hex string
+  # @!attribute [r] badges
+  #   @return [Hash]
+  # @!attribute [r] card_members
+  #   @return [Object]
   class Card < BasicData
     register_attributes :id, :short_id, :name, :desc, :due, :closed, :url, :short_url,
       :board_id, :member_ids, :list_id, :pos, :last_activity_date, :card_labels,
       :cover_image_id, :badges, :card_members,
-      :readonly => [ :id, :short_id, :url, :short_url, :last_activity_date, :badges, :card_members ]
+      readonly: [ :id, :short_id, :url, :short_url, :last_activity_date, :badges, :card_members ]
     validates_presence_of :id, :name, :list_id
-    validates_length_of   :name,        :in => 1..16384
-    validates_length_of   :desc, :in => 0..16384
+    validates_length_of   :name,        in: 1..16384
+    validates_length_of   :desc, in: 0..16384
 
     include HasActions
 
@@ -33,11 +68,32 @@ module Trello
 
     class << self
       # Find a specific card by its id.
+      #
+      # @raise [Trello::Error] if the card could not be found.
+      #
+      # @return [Trello::Card]
       def find(id, params = {})
         client.find(:card, id, params)
       end
 
       # Create a new card and save it on Trello.
+      #
+      # @param [Hash] options # @option options [String] :name The name of the new card.
+      # @option options [String] :list_id ID of the list that the card should
+      #     be added to.
+      # @option options [String] :desc A string with a
+      #     length from 0 to 16384.
+      # @option options [String] :member_ids A comma-separated list of
+      #     objectIds (24-character hex strings).
+      # @option options [String] :card_labels A comma-separated list of
+      #     objectIds (24-character hex strings).
+      # @option options [Date] :due A date, or `nil`.
+      # @option options [String] :pos A position. `"top"`, `"bottom"`, or a
+      #     positive number. Defaults to `"bottom"`.
+      #
+      # @raise [Trello::Error] if the card could not be created.
+      #
+      # @return [Trello::Card]
       def create(options)
         client.create(:card,
           'name' => options[:name],
@@ -55,6 +111,34 @@ module Trello
     #
     # Supply a hash of string keyed data retrieved from the Trello API representing
     # a card.
+    #
+    # Note that this this method does not save anything new to the Trello API,
+    # it just assigns the input attributes to your local object. If you use
+    # this method to assign attributes, call `save` or `update!` afterwards if
+    # you want to persist your changes to Trello.
+    #
+    # @param [Hash] fields
+    # @option fields [String] :id
+    # @option fields [String] :short_id
+    # @option fields [String] :name The new name of the card.
+    # @option fields [String] :desc A string with a length from 0 to
+    #     16384.
+    # @option fields [Date] :due A date, or `nil`.
+    # @option fields [Boolean] :closed
+    # @option fields [String] :url
+    # @option fields [String] :short_url
+    # @option fields [String] :board_id
+    # @option fields [String] :member_ids A comma-separated list of objectIds
+    #     (24-character hex strings).
+    # @option fields [String] :pos A position. `"top"`, `"bottom"`, or a
+    #     positive number. Defaults to `"bottom"`.
+    # @option fields [String] :card_labels A comma-separated list of
+    #     objectIds (24-character hex strings).
+    # @option fields [Object] :cover_image_id
+    # @option fields [Object] :badges
+    # @option fields [Object] :card_members
+    #
+    # @return [Trello::Card] self
     def update_fields(fields)
       attributes[:id]                 = fields[SYMBOL_TO_STRING[:id]]
       attributes[:short_id]           = fields[SYMBOL_TO_STRING[:short_id]]
@@ -77,16 +161,16 @@ module Trello
     end
 
     # Returns a reference to the board this card is part of.
-    one :board, :path => :boards, :using => :board_id
+    one :board, path: :boards, using: :board_id
     # Returns a reference to the cover image attachment
-    one :cover_image, :path => :attachments, :using => :cover_image_id
+    one :cover_image, path: :attachments, using: :cover_image_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
+    many :checklists, filter: :all
 
     def check_item_states
       states = client.get("/cards/#{self.id}/checkItemStates").json_into(CheckItemState)
@@ -95,9 +179,11 @@ module Trello
 
 
     # Returns a reference to the list this card is currently in.
-    one :list, :path => :lists, :using => :list_id
+    one :list, path: :lists, using: :list_id
 
     # Returns a list of members who are assigned to this card.
+    #
+    # @return [Array<Trello::Member>]
     def members
       members = member_ids.map do |member_id|
         client.get("/members/#{member_id}").json_into(Member)
@@ -106,6 +192,11 @@ module Trello
     end
 
     # Saves a record.
+    #
+    # @raise [Trello::Error] if the card could not be saved
+    #
+    # @return [String] The JSON representation of the saved card returned by
+    #     the Trello API.
     def save
       # If we have an id, just update our fields.
       return update! if id
@@ -121,9 +212,15 @@ module Trello
     end
 
     # Update an existing record.
-    # Warning, this updates all fields using values already in memory. If
+    #
+    # 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.
+    #
+    # @raise [Trello::Error] if the card could not be updated.
+    #
+    # @return [String] The JSON representation of the updated card returned by
+    #     the Trello API.
     def update!
       @previously_changed = changes
       # extract only new values to build payload
@@ -133,7 +230,10 @@ module Trello
       client.put("/cards/#{id}", payload)
     end
 
+
     # Delete this card
+    #
+    # @return [String] the JSON response from the Trello API
     def delete
       client.delete("/cards/#{id}")
     end
@@ -143,6 +243,15 @@ module Trello
       closed
     end
 
+    # Close the card.
+    #
+    # This only marks your local copy card as closed. Use `close!` if you
+    # want to close the card and persist the change to the Trello API.
+    #
+    # @return [Boolean] always returns true
+    #
+    # @return [String] The JSON representation of the closed card returned by
+    #     the Trello API.
     def close
       self.closed = true
     end
@@ -159,13 +268,13 @@ module Trello
 
     # Add a comment with the supplied text.
     def add_comment(text)
-      client.post("/cards/#{id}/actions/comments", :text => 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
+        value: checklist.id
       })
     end
 
@@ -187,7 +296,7 @@ module Trello
     # Move this card to the given board (and optional list on this board)
     def move_to_board(new_board, new_list = nil)
       unless board_id == new_board.id
-        payload = { :value => new_board.id }
+        payload = { value: new_board.id }
         payload[:idList] = new_list.id if new_list
         client.put("/cards/#{id}/idBoard", payload)
       end
@@ -196,7 +305,7 @@ module Trello
     # Add a member to this card
     def add_member(member)
       client.post("/cards/#{id}/members", {
-        :value => member.id
+        value: member.id
       })
     end
 
@@ -222,7 +331,7 @@ module Trello
         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 })
+      client.post("/cards/#{id}/labels", { value: colour })
     end
 
     # Remove a label
@@ -238,13 +347,13 @@ module Trello
     def add_attachment(attachment, name='')
       if attachment.is_a? File
         client.post("/cards/#{id}/attachments", {
-            :file => attachment,
-            :name => name
+            file: attachment,
+            name: name
           })
       else
         client.post("/cards/#{id}/attachments", {
-            :url => attachment,
-            :name => name
+            url: attachment,
+            name: name
           })
       end
     end
@@ -255,7 +364,7 @@ module Trello
       MultiAssociation.new(self, attachments).proxy
     end
 
-      # Remove an attachment from this card
+    # Remove an attachment from this card
     def remove_attachment(attachment)
       client.delete("/cards/#{id}/attachments/#{attachment.id}")
     end