tacokit 0.1.0 → 0.2.0

data/lib/tacokit/client/boards.rb

@@ -1,83 +1,87 @@
 module Tacokit
   class Client
     module Boards
-
-      # GET /1/boards/[board_id]
+      # Retrieve a board
+      #
+      # @see https://trello.com/docs/api/board/index.html#get-1-boards-board-id
       def board(board_id, options = nil)
         get board_path(board_id), options
       end
 
-      # GET /1/boards/[board_id]/[field]
-      def board_field(board_id, field, options = nil)
-        get board_path(board_id, camp(field)), options
-      end
-
-      # GET /1/boards/[board_id]/[resource]
-      # actions
-      # boardStars
-      # cards
-      # cards/[filter]
-      # cards/[idCard]
-      # checklists
-      # deltas
-      # labels
-      # labels/[idLabel]
-      # lists
-      # lists/[filter]
-      # members
-      # members/[filter]
-      # members/[idMember]/cards
-      # membersInvited
-      # membersInvited/[field]
-      # memberships
-      # memberships/[idMembership]
-      # myPrefs
-      # organization
-      # organization/[field]
-      def board_resource(board_id, resource, *paths)
-        paths, options = extract_options(camp(resource), *paths)
-        get board_path(board_id, *paths), options
+      # Retrieve a board's actions
+      #
+      # @see https://trello.com/docs/api/board/index.html#get-1-boards-board-id-actions
+      def board_actions(board_id, options = {})
+        paginated_board_resource(board_id, "actions", options)
+      end
+
+      # Retrieve a board's stars
+      #
+      # @see https://trello.com/docs/api/board/index.html#get-1-boards-board-id-boardstars
+      def board_stars(board_id, options = {})
+        board_resource(board_id, "board_stars", options)
+      end
+
+      # Retrieve a board's cards
+      #
+      # @see https://trello.com/docs/api/board/index.html#get-1-boards-board-id-cards
+      def board_cards(board_id, options = {})
+        paginated_board_resource(board_id, "cards", options)
+      end
+
+      # Retrieve a board's checklists
+      #
+      # @see https://trello.com/docs/api/board/index.html#get-1-boards-board-id-checklists
+      def board_checklists(board_id, options = {})
+        board_resource(board_id, "checklists", options)
+      end
+
+      # Retrieve a board's labels
+      #
+      # @see https://trello.com/docs/api/board/index.html#get-1-boards-board-id-labels
+      def board_labels(board_id, options = {})
+        board_resource(board_id, "labels", options)
+      end
+
+      # Retrieve a board's lists
+      #
+      # @see https://trello.com/docs/api/board/index.html#get-1-boards-board-id-lists
+      def lists(board_id, options = {})
+        board_resource(board_id, "lists", options)
+      end
+      alias_method :board_lists, :lists
+
+      # Retrieve a board's members
+      #
+      # @see https://trello.com/docs/api/board/index.html#get-1-boards-board-id-members
+      def board_members(board_id, options = {})
+        board_resource(board_id, "members", options)
+      end
+
+      # Retrieve your preferences for a board
+      #
+      # @see https://trello.com/docs/api/board/index.html#get-1-boards-board-id-myprefs
+      def board_preferences(board_id, options = {})
+        board_resource(board_id, "my_prefs", options)
+      end
+
+      # Retrieve a board's organization
+      #
+      # @see https://trello.com/docs/api/board/index.html#get-1-boards-board-id-organization
+      def board_organization(board_id, options = {})
+        board_resource(board_id, "organization", options)
       end
 
-      # PUT /1/boards/[board_id]
+      # Update board attributes
+      #
+      # @see https://trello.com/docs/api/board/index.html#put-1-boards-board-id
       def update_board(board_id, options = {})
         put board_path(board_id), options
       end
 
-      # PUT /1/boards/[board_id]/[field]
-      # closed
-      # desc
-      # idOrganization
-      # labelNames/blue
-      # labelNames/green
-      # labelNames/orange
-      # labelNames/purple
-      # labelNames/red
-      # labelNames/yellow
-      # myPrefs/emailPosition
-      # myPrefs/idEmailList
-      # myPrefs/showListGuide
-      # myPrefs/showSidebar
-      # myPrefs/showSidebarActivity
-      # myPrefs/showSidebarBoardActions
-      # myPrefs/showSidebarMembers
-      # name
-      # prefs/background
-      # prefs/calendarFeedEnabled
-      # prefs/cardAging
-      # prefs/cardCovers
-      # prefs/comments
-      # prefs/invitations
-      # prefs/permissionLevel
-      # prefs/selfJoin
-      # prefs/voting
-      # subscribed
-      def update_board_field(board_id, *paths)
-        value = paths.pop
-        put board_path(board_id, camel_join(*paths)), value: value
-      end
-
-      # PUT /1/boards/[board_id]/members
+      # Add a member to a board
+      #
+      # @see https://trello.com/docs/api/board/index.html#put-1-boards-board-id-members-idmember
       def add_board_member(board_id, email, full_name, options = {})
         options.update \
           email: email,
@@ -85,11 +89,11 @@ module Tacokit
         put board_path(board_id, "members"), options
       end
 
-      # PUT /1/boards/[board_id]/[resource]
-      # members/[idMember]
-      # memberships/[idMembership]
-      def update_board_resource(board_id, resource, resource_id, options = {})
-        put board_path(board_id, camp(resource), resource_id), options
+      # Update a board member's type
+      #
+      # @see https://trello.com/docs/api/board/index.html#put-1-boards-board-id-members-idmember
+      def update_board_member(board_id, member_id, type)
+        update_board_resource(board_id, "members", member_id, type: type)
       end
 
       # POST /1/boards
@@ -97,28 +101,31 @@ module Tacokit
         post board_path, options.merge(name: name)
       end
 
-      # POST /1/boards/[board_id]/[resource]
-      # calendarKey/generate
-      # checklists
-      # emailKey/generate
-      # labels
-      # lists
-      # markAsViewed
-      # powerUps
+      private
+
       def create_board_resource(board_id, resource, *paths)
         paths, options = extract_options(camp(resource), *paths)
         post board_path(board_id, *paths), options
       end
 
-      # DELETE /1/boards/[board_id]/[resource]/[resource_id]
-      # members/[idMember]
-      # powerUps/[powerUp]
-      #
+      def update_board_resource(board_id, resource, *paths)
+        paths, options = extract_options(camp(resource), *paths)
+        put board_path(board_id, *paths), options
+      end
+
+      def board_resource(board_id, resource, *paths)
+        paths, options = extract_options(camp(resource), *paths)
+        get board_path(board_id, *paths), options
+      end
+
+      def paginated_board_resource(board_id, resource, *paths)
+        paths, options = extract_options(camp(resource), *paths)
+        paginated_get board_path(board_id, *paths), options
+      end
 
       def board_path(*paths)
         path_join("boards", *paths)
       end
-
     end
   end
 end

data/lib/tacokit/client/cards.rb

@@ -1,96 +1,183 @@
 module Tacokit
   class Client
+    # Methods for the Cards API
+    #
+    # @see https://trello.com/docs/api/card/index.html
     module Cards
-
-      # GET cards/[card id or shortlink]
+      # Retrieve a card by id or shortlink
+      #
+      # @see https://trello.com/docs/api/card/index.html#get-1-cards-card-id-or-shortlink
       def card(card_id, options = nil)
         get card_path(card_id), options
       end
 
-      # GET cards/[card id or shortlink]/[field]
-      # badges
-      # checkItemStates
-      # closed
-      # dateLastActivity
-      # desc
-      # descData
-      # due
-      # email
-      # idAttachmentCover
-      # idBoard
-      # idChecklists
-      # idLabels
-      # idList
-      # idMembers
-      # idMembersVoted
-      # idShort
-      # labels
-      # manualCoverAttachment
-      # name
-      # pos
-      # shortLink
-      # shortUrl
-      # subscribed
-      # url
-      def card_field(card_id, field, options = nil)
-        get card_path(card_id, camp(field)), options
-      end
-
-      # GET cards/[card id or shortlink]/[resource]
-      # actions
-      # attachments
-      # attachments/[idAttachment]
-      # board
-      # board/[field]
-      # checkItemStates
-      # checklists
-      # list
-      # list/[field]
-      # members
-      # membersVoted
-      # stickers
-      # stickers/[idSticker]
-      def card_resource(card_id, resource, options = {})
-        get card_path(card_id, camp(resource)), options
+      # Retrieve card actions
+      #
+      # @see https://trello.com/docs/api/card/index.html#get-1-cards-card-id-or-shortlink-actions
+      def card_actions(card_id, options = {})
+        paginated_card_resource(card_id, "actions", options)
+      end
+
+      # Retrieve card attachments
+      #
+      # @see https://trello.com/docs/api/card/index.html#get-1-cards-card-id-or-shortlink-attachments
+      def attachments(card_id, options = {})
+        card_resource(card_id, "attachments", options)
+      end
+      alias_method :card_attachments, :attachments
+
+      # Retrieve a card attachment
+      #
+      # @see https://trello.com/docs/api/card/index.html#get-1-cards-card-id-or-shortlink-attachments-idattachment
+      def attachment(card_id, attachment_id, options = {})
+        card_resource(card_id, "attachments/#{attachment_id}", options)
+      end
+
+      # Retrieve a card board
+      #
+      # @see https://trello.com/docs/api/card/index.html#get-1-cards-card-id-or-shortlink-board
+      def card_board(card_id, options = {})
+        card_resource(card_id, "board", options)
+      end
+
+      # Retrieve card checklist item states
+      #
+      # @see https://trello.com/docs/api/card/index.html#get-1-cards-card-id-or-shortlink-board
+      def check_item_states(card_id, options = {})
+        card_resource(card_id, "check_item_states", options)
+      end
+
+      # Retrieve card checklists
+      #
+      # @see https://trello.com/docs/api/card/index.html#get-1-cards-card-id-or-shortlink-board
+      def checklists(card_id, options = {})
+        card_resource(card_id, "checklists", options)
+      end
+
+      # Retrive a card list
+      #
+      # @see https://trello.com/docs/api/card/index.html#get-1-cards-card-id-or-shortlink-list
+      def card_list(card_id, options = {})
+        card_resource(card_id, "list", options)
       end
 
-      # PUT cards/[card id or shortlink]
+      # Retrieve card members
+      #
+      # @see https://trello.com/docs/api/card/index.html#get-1-cards-card-id-or-shortlink-members
+      def card_members(card_id, options = {})
+        card_resource(card_id, "members", options)
+      end
+
+      # Retrieve members who voted on a card
+      #
+      # @see https://trello.com/docs/api/card/index.html#get-1-cards-card-id-or-shortlink-membersvoted
+      def card_members_voted(card_id, options = {})
+        card_resource(card_id, "members_voted", options)
+      end
+
+      # Retrieve card stickers
+      #
+      # @see https://trello.com/docs/api/card/index.html#get-1-cards-card-id-or-shortlink-stickers
+      def stickers(card_id, options = {})
+        card_resource(card_id, "stickers", options)
+      end
+
+      # Update card attributes
+      #
+      # @see https://trello.com/docs/api/card/index.html#put-1-cards-card-id-or-shortlink
       def update_card(card_id, options = {})
         put card_path(card_id), options
       end
 
-      # PUT cards/[card id or shortlink]/[resource]
-      # actions/[idAction]/comments
-      # checklist/[idChecklist]/checkItem/[idCheckItem]/name
-      # checklist/[idChecklist]/checkItem/[idCheckItem]/pos
-      # checklist/[idChecklist]/checkItem/[idCheckItem]/state
-      # checklist/[idChecklistCurrent]/checkItem/[idCheckItem]
-      # closed
-      # desc
-      # due
-      # idAttachmentCover
-      # idBoard
-      # idList
-      # idMembers
-      # labels
-      # name
-      # pos
-      # stickers/[idSticker]
-      # subscribed
-
-      # POST cards
+      # Update comment text
+      #
+      # @see https://trello.com/docs/api/card/index.html#put-1-cards-card-id-or-shortlink-actions-idaction-comments
+      def update_comment(card_id, comment_id, text, options = {})
+        update_card_resource(card_id, "actions", comment_id, "comments", options.merge(text: text))
+      end
+      alias_method :edit_comment, :update_comment
+
+      # Update checklist item text, position or state
+      #
+      # @see https://trello.com/docs/api/card/index.html#put-1-cards-card-id-or-shortlink-checklist-idchecklistcurrent-checkitem-idcheckitem
+      def update_check_item(card_id, checklist_id, check_item_id, options = {})
+        update_card_resource(card_id, "checklist", checklist_id, "checkItem", check_item_id, options)
+      end
+
+      # Archive a card
+      #
+      # @see https://trello.com/docs/api/card/index.html#put-1-cards-card-id-or-shortlink-closed
+      def archive_card(card_id)
+        update_card(card_id, closed: true)
+      end
+
+      # Restore an archived card
+      #
+      # @see https://trello.com/docs/api/card/index.html#put-1-cards-card-id-or-shortlink-closed
+      def restore_card(card_id)
+        update_card(card_id, closed: false)
+      end
+
+      # Move card to another position, board and/or list
+      #
+      # @see https://trello.com/docs/api/card/index.html#put-1-cards-card-id-or-shortlink-idboard
+      # @see https://trello.com/docs/api/card/index.html#put-1-cards-card-id-or-shortlink-idlist
+      def move_card(card_id, options)
+        unless options.is_a?(Hash) && ([:board_id, :list_id, :pos].any? { |key| options.key? key })
+          raise ArgumentError, "Required option: :pos, :board_id and/or :list_id"
+        end
+        update_card(card_id, options)
+      end
+
+      # Update card name
+      #
+      # @see https://trello.com/docs/api/card/index.html#put-1-cards-card-id-or-shortlink-name
+      def update_card_name(card_id, name)
+        put card_path(card_id, "name"), value: name
+      end
+
+      # Subscribe to card
+      #
+      # @see https://trello.com/docs/api/card/index.html#put-1-cards-card-id-or-shortlink-subscribed
+      def subscribe_to_card(card_id)
+        put card_path(card_id, "subscribed"), value: true
+      end
+
+      # Unubscribe from card
+      #
+      # @see https://trello.com/docs/api/card/index.html#put-1-cards-card-id-or-shortlink-subscribed
+      def unsubscribe_from_card(card_id)
+        put card_path(card_id, "subscribed"), value: false
+      end
+
+      # Update any card resource
+      def update_card_resource(card_id, resource, *paths)
+        paths, options = extract_options(camp(resource), *paths)
+        put card_path(card_id, *paths), options
+      end
+
+      # Create a card
+      #
+      # @see https://trello.com/docs/api/card/index.html#post-1-cards
       def create_card(list_id, name = nil, options = {})
         post card_path, options.merge(name: name, list_id: list_id)
       end
 
-      # POST cards/[card id or shortlink]/actions/comments
-      def create_card_comment(card_id, text, options = {})
+      # Add a comment to a card
+      #
+      # @see https://trello.com/docs/api/card/index.html#post-1-cards-card-id-or-shortlink-actions-comments
+      def add_comment(card_id, text, options = {})
         options.update text: text
         create_card_resource card_id, "actions", "comments", options
       end
+      alias_method :create_card_comment, :add_comment
+
+      # Attach a file to a card
+      #
+      # @see https://trello.com/docs/api/card/index.html#post-1-cards-card-id-or-shortlink-attachments
+      def attach_file(card_id, url, mime_type = nil, options = {})
+        options = mime_type if mime_type.is_a?(Hash)
 
-      # POST cards/[card id or shortlink]/attachments
-      def create_card_attachment(card_id, url, mime_type = nil, options = {})
         uri = Addressable::URI.parse(url)
 
         if uri.scheme =~ %r{https?}
@@ -100,43 +187,149 @@ module Tacokit
           options.update file: file, mime_type: file.content_type
         end
 
-        create_card_resource card_id, 'attachments', options
+        create_card_resource card_id, "attachments", options
+      end
+      alias_method :create_card_attachment, :attach_file
+
+      # Convert a checklist item to a card
+      #
+      # @see https://trello.com/docs/api/card/index.html#post-1-cards-card-id-or-shortlink-checklist-idchecklist-checkitem-idcheckitem-converttocard
+      def convert_to_card(card_id, checklist_id, check_item_id)
+        create_card_resource(card_id, "checklist", checklist_id, "checkItem", check_item_id, "convertToCard")
       end
 
-      # POST cards/[card id or shortlink]/[resource]
-      # checklist/[idChecklist]/checkItem
-      # checklist/[idChecklist]/checkItem/[idCheckItem]/convertToCard
-      # checklists
-      # idMembers
-      # labels
-      # markAssociatedNotificationsRead
-      # membersVoted
-      # stickers
+      # Start a new checklist on card
+      #
+      # @see https://trello.com/docs/api/card/index.html#post-1-cards-card-id-or-shortlink-checklists
+      def add_checklist(card_id, name)
+        create_card_resource(card_id, "checklists", name: name)
+      end
+      alias_method :start_checklist, :add_checklist
+
+      # Copy another checklist to card
+      #
+      # @see https://trello.com/docs/api/card/index.html#post-1-cards-card-id-or-shortlink-checklists
+      def copy_checklist(card_id, checklist_id)
+        create_card_resource(card_id, "checklists", checklist_source_id: checklist_id)
+      end
+
+      # Add a member to a card
+      #
+      # @see https://trello.com/docs/api/card/index.html#post-1-cards-card-id-or-shortlink-idmembers
+      def add_member_to_card(card_id, member_id)
+        create_card_resource(card_id, "idMembers", value: member_id)
+      end
+
+      # Add label to card
+      #
+      # @see https://trello.com/docs/api/card/index.html#post-1-cards-card-id-or-shortlink-labels
+      def add_label(card_id, color, options = {})
+        create_card_resource(card_id, "labels", options.merge(color: color))
+      end
+
+      # Cast vote for card
+      #
+      # @see https://trello.com/docs/api/card/index.html#post-1-cards-card-id-or-shortlink-membersvoted
+      def vote(card_id, member_id)
+        create_card_resource(card_id, "membersVoted", value: member_id)
+      end
+      alias_method :create_vote, :vote
+
+      # Add sticker to card
+      #
+      # @see https://trello.com/docs/api/card/index.html#post-1-cards-card-id-or-shortlink-stickers
+      def add_sticker(card_id, image_name, options = {})
+        defaults = { top: 0, left: 0, z_index: 1 }
+        create_card_resource(card_id, "stickers", defaults.merge(options.merge(image: image_name)))
+      end
+      alias_method :create_sticker, :add_sticker
+
+      # Create a card resource
+      #
       def create_card_resource(card_id, resource, *paths)
         paths, options = extract_options(camp(resource), *paths)
         post card_path(card_id, *paths), options
       end
 
       # DELETE cards/[card id or shortlink]
+      #
+      # @see https://trello.com/docs/api/card/index.html#delete-1-cards-card-id-or-shortlink
       def delete_card(card_id)
         delete card_path(card_id)
       end
 
-      # DELETE cards/[card id or shortlink]/[resource]
-      # actions/[idAction]/comments
-      # attachments/[idAttachment]
-      # checklist/[idChecklist]/checkItem/[idCheckItem]
-      # checklists/[idChecklist]
-      # idMembers/[idMember]
-      # labels/[color]
-      # membersVoted/[idMember]
-      # stickers/[idSticker]
+      # Remove a comment
+      #
+      # @see https://trello.com/docs/api/card/index.html#post-1-cards-card-id-or-shortlink-labels
+      def remove_comment(card_id, comment_id)
+        delete_card_resource card_id, "actions", comment_id, "comments"
+      end
+      alias_method :delete_comment, :remove_comment
+
+      # Remove an attachment
+      #
+      # @see https://trello.com/docs/api/card/index.html#delete-1-cards-card-id-or-shortlink-attachments-idattachment
+      def remove_attachment(card_id, attachment_id)
+        delete_card_resource card_id, "attachments", attachment_id
+      end
+      alias_method :delete_attachement, :remove_attachment
+
+      # Remove checklist
+      #
+      # @see https://trello.com/docs/api/card/index.html#delete-1-cards-card-id-or-shortlink-checklists-idchecklist
+      def remove_checklist(card_id, checklist_id)
+        delete_card_resource card_id, "checklists", checklist_id
+      end
+      alias_method :delete_checklist, :remove_checklist
+
+      # Remove a member from a card
+      #
+      # @see https://trello.com/docs/api/card/index.html#delete-1-cards-card-id-or-shortlink-idmembers-idmember
+      def remove_card_member(card_id, member_id)
+        delete_card_resource card_id, "idMembers", member_id
+      end
+      alias_method :delete_card_member, :remove_card_member
+
+      # Remove label from card
+      #
+      # @see https://trello.com/docs/api/card/index.html#delete-1-cards-card-id-or-shortlink-labels-color
+      def remove_label(card_id, color)
+        delete_card_resource card_id, "labels", color
+      end
+      alias_method :delete_label, :remove_label
+
+      # Remove a vote from a card
+      #
+      # @see https://trello.com/docs/api/card/index.html#delete-1-cards-card-id-or-shortlink-membersvoted-idmember
+      def remove_vote(card_id, member_id)
+        delete_card_resource card_id, "membersVoted", member_id
+      end
+      alias_method :delete_vote, :remove_vote
+
+      # Remove a sticker from a card
+      #
+      # @see https://trello.com/docs/api/card/index.html#delete-1-cards-card-id-or-shortlink-membersvoted-idmember
+      def remove_sticker(card_id, sticker_id)
+        delete_card_resource card_id, "stickers", sticker_id
+      end
+      alias_method :delete_sticker, :remove_sticker
+
+      private
+
+      def card_resource(card_id, resource, options = {})
+        get card_path(card_id, camp(resource)), options
+      end
+
+      def paginated_card_resource(card_id, resource, options = {})
+        paginated_get card_path(card_id, camp(resource)), options
+      end
+
       def delete_card_resource(card_id, resource, *paths)
         delete card_path(card_id, camp(resource), *paths)
       end
 
       def card_path(*paths)
-        path_join "cards", *paths
+        base_path "cards", *paths
       end
     end
   end