tacokit 0.3.1 → 0.4.0

data/lib/tacokit/client/checklists.rb

@@ -2,67 +2,78 @@ module Tacokit
   class Client
     module Checklists
       # Retrieve a checklist
-      #
+      # @param checklist_id [String] the checklist identifier
+      # @param options [Hash] options to fetch the checklist with
+      # @return [Tacokit::Resource] the checklist resource
       # @see https://developers.trello.com/advanced-reference/checklist#get-1-checklists-idchecklist
       def checklist(checklist_id, options = nil)
         get checklist_path(checklist_id), options
       end
 
       # Retrieve the checklist's board
-      #
+      # @param checklist_id [String] the checklist identifier
+      # @param options [Hash] the options to fetch the board with
+      # @return [Tacokit::Resource] the board resource
       # @see https://developers.trello.com/advanced-reference/checklist#get-1-checklists-idchecklist-board
       def checklist_board(checklist_id, options = {})
         checklist_resource checklist_list_id, "board", options
       end
 
       # Retrieve a checklist's card
-      #
+      # @param checklist_id [String] the checklist identifier
+      # @param options [Hash] the options to fetch the card with
+      # @return [Tacokit::Resource] the card resource
       # @see https://developers.trello.com/advanced-reference/checklist#get-1-checklists-idchecklist-cards
       def checklist_card(checklist_id, options = {})
         checklist_resource checklist_id, "card", options
       end
 
       # Retrieve a checklist's check items
-      #
+      # @param checklist_id [String] the checklist identifier
+      # @param options [Hash] the options to fetch the checklist with
+      # @return [Array] the check items collection
       # @see https://developers.trello.com/advanced-reference/checklist#get-1-checklists-idchecklist-checkitems
       def check_items(checklist_id, options = {})
         checklist_resource checklist_id, "check_items", options
       end
-      alias_method :checklist_check_items, :check_items
+      alias checklist_check_items check_items
 
       # Updates a checklist
-      #
+      # @param checklist_id [String] the checklist identifier
+      # @param options [Hash] the options to update the checklist with
       # @see https://developers.trello.com/advanced-reference/checklist#put-1-checklists-idchecklist
       def update_checklist(checklist_id, options = {})
         put checklist_path(checklist_id), options
       end
-      alias_method :checklist_update, :update_checklist
+      alias checklist_update update_checklist
 
       # Create a checklist
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param name [String] name for the checklist
       # @see https://developers.trello.com/advanced-reference/checklist#post-1-checklists
       def create_checklist(card_id, name, options = {})
         options.update card_id: card_id, name: name
         post "checklists", options
       end
-      alias_method :checklist_create, :create_checklist
+      alias checklist_create create_checklist
 
       # Add a checklist item to a checklist
-      #
+      # @param checklist_id [String] the checklist identifier
+      # @param name [String] name for the check item
       # @see https://developers.trello.com/advanced-reference/checklist#post-1-checklists-idchecklist-checkitems
       def add_checklist_check_item(checklist_id, name, options = {})
         post checklist_path(checklist_id, "checkItems"), options.merge(name: name)
       end
-      alias_method :checklist_check_item_create, :add_checklist_check_item
-      alias_method :add_checklist_item, :add_checklist_check_item
+      alias checklist_check_item_create add_checklist_check_item
+      alias add_checklist_item add_checklist_check_item
 
       # Delete a checklist
-      #
+      # @param checklist_id [String] the checklist identifier
       # @see https://developers.trello.com/advanced-reference/checklist#delete-1-checklists-idchecklist
       def delete_checklist(checklist_id)
         delete checklist_path(checklist_id)
       end
-      alias_method :checklist_delete, :delete_checklist
+      alias checklist_delete delete_checklist
 
       private
 

data/lib/tacokit/client/labels.rb

@@ -2,21 +2,28 @@ module Tacokit
   class Client
     module Labels
       # Retrieve a label
-      #
+      # @param label_id [String] the label identifier
+      # @param options [Hash] options to fetch the label with
+      # @return [Tacokit::Resource] the label resource
       # @see https://developers.trello.com/advanced-reference/label#get-1-labels-idlabel
       def label(label_id, options = nil)
         get label_path(label_id), options
       end
 
       # Update a label
-      #
+      # @param label_id [String] the label identifier
+      # @param options [Hash] the options to update the label with
+      # @return [Tacokit::Resource] the label resource
       # @see https://developers.trello.com/advanced-reference/label#put-1-labels-idlabel
       def update_label(label_id, options = {})
         put label_path(label_id), options
       end
 
       # Create a label
-      #
+      # @param board_id [String] the board identifier
+      # @param name [String] the label name
+      # @param color [String] the label color
+      # @return [Tacokit::Resource] the label resource
       # @see https://developers.trello.com/advanced-reference/label#post-1-labels
       def create_label(board_id, name, color)
         post "labels",
@@ -26,7 +33,7 @@ module Tacokit
       end
 
       # Delete a label
-      #
+      # @param label_id [String] the label identifier
       # @see https://developers.trello.com/advanced-reference/label#delete-1-labels-idlabel
       def delete_label(label_id)
         delete label_path(label_id)

data/lib/tacokit/client/lists.rb

@@ -1,65 +1,118 @@
 module Tacokit
   class Client
+    # Methods for the Lists API
+    # @see https://developers.trello.com/advanced-reference/list
     module Lists
       # Retrieve a list by id
-      #
+      # @param list_id [String] the list identifier or shortlink
+      # @return [Tacokit::Resource<List>] the list resource
+      # @example Retrieve a list by its id with its open cards
+      #   Tacokit.list("aListId", cards: "open") #=> Tacokit::Resource<List>
       # @see https://developers.trello.com/advanced-reference/list#get-1-labels-idlabel-board
       def list(list_id, options = nil)
         get list_path(list_id), options
       end
 
-      # Retrive a list's actions
-      #
+      # Retrieve list's actions
+      # @param list_id [String, Tacokit::Resource<List>] the list identifier, shortlink, or list
+      # @param options [Hash] the options to fetch the actions with
+      # @return [Tacokit::Collection<Action>] the action resources
+      # @example fetch "comment" actions for a given list
+      #   list = Tacokit.list("aListId") #=> Tacokit::Resource<List>
+      #   Tacokit.list_actions(list, filter: "comment_card") #=> Tacokit::Collection<Action>
       # @see https://developers.trello.com/advanced-reference/list#get-1-lists-idlist-actions
       def list_actions(list_id, options = {})
         paginated_list_resource list_id, "actions", options
       end
 
-      # Retrive a list's board
-      #
+      # Retrieve a list's board
+      # @param list_id [String, Tacokit::Resource<List>] the list identifier, shortlink, or list
+      # @param options [Hash] the options to fetch the board with
+      # @return [Tacokit::Resource<Board>] the board resource
+      # @example fetch a list's board
+      #   list = Tacokit.list("aListId") #=> Tacokit::Resource<List>
+      #   Tacokit.list_board(list) #=> Tacokit::Resource<Board>
       # @see https://developers.trello.com/advanced-reference/list#get-1-lists-idlist-board
       def list_board(list_id, options = {})
         list_resource list_id, "board", options
       end
 
       # Retrive a list's cards
-      #
+      # @param list_id [String, Tacokit::Resource<List>] the list identifier or list
+      # @param options [Hash] the options to fetch the cards with
+      # @return [Tacokit::Collection<Card>] the card resources
+      # @example fetch list cards
+      #   list = Tacokit.list("aListId") #=> Tacokit::Resource<List>
+      #   Tacokit.list_cards(list) #=> Tacokit::Collection<Card>
+      # @example fetch list cards with attachments, members, stickers
+      #   Tacokit.list_cards(list, attachments: true, members: true, stickers: true) #=> Tacokit::Collection<Card>
+      # @example configure a local client, fetch a list"s cards with a subset of attributes
+      #   client = Tacokit::Client.new app_key: "another-app-key"
+      #   client.list_cards(list) #=> Tacokit::Collection<Card>
       # @see https://developers.trello.com/advanced-reference/list#get-1-lists-idlist-cards
       def list_cards(list_id, options = {})
         paginated_list_resource list_id, "cards", options
       end
 
       # Update a list's attributes
-      #
+      # @param list_id [String, Tacokit::Resource<List>] the list identifier, shortlink, or list
+      # @param options [Hash] the attributes to update on the list
+      # @return [Tacokit::Resource<List>] the list resource
+      # @example Change a list's name and position
+      #   list = Tacokit.list("aListId") #=> Tacokit::Resource<List>
+      #   Tacokit.update_list(list, name: "New Name", pos: "top") #=> Tacokit::Resource<List>
       # @see https://developers.trello.com/advanced-reference/list#put-1-lists-idlis
       def update_list(list_id, options = {})
         put list_path(list_id), options
       end
 
       # Create a new list
-      #
+      # @param board_id [String] the board identifier
+      # @param name [String] a name for the list
+      # @param options [Hash] options to create the list with
+      # @return [Tacokit::Resource<List>] the list resource
+      # @example Create a new list on the top
+      #   board = Tacokit.board("aBoardId")
+      #   Tacokit.create_list(board, "New List", pos: "top")  #=> Tacokit::Resource<List>
       # @see https://developers.trello.com/advanced-reference/list#post-1-lists
       def create_list(board_id, name, options = {})
-        post "lists", options.merge(name: name, board_id: board_id)
+        post "lists", options.merge(name: name, board_id: resource_id(board_id))
       end
 
       # Archive all cards in a list
-      #
+      # @param list_id [String, Tacokit::Resource<Card>] the list identifier, shortlink, or list
+      # @example Archive cards
+      #   list = Tacokit.list("aListId") #=> Tacokit::Resource<List>
+      #   Tacokit.archive_all_cards(list)
       # @see https://developers.trello.com/advanced-reference/list#post-1-lists-idlist-moveallcards
       def archive_list_cards(list_id)
         post list_path(list_id, camp("archive_all_cards"))
       end
 
       # Move cards from one list to another
-      #
+      # @param list_id [String, Tacokit::Resource<List>] the source list identifier or list
+      # @param destination_list_id [String, Tacokit::Resource<List>] the destination list identifier
+      # @param board_id [String] the board identifier
+      # @example Move cards from list A to B
+      #   listA = Tacokit.list("aListId") #=> Tacokit::Resource<List>
+      #   listB = Tacokit.list("bListId") #=> Tacokit::Resource<List>
+      #   Tacokit.move_all_cards(listA, listB)
       # @see https://developers.trello.com/advanced-reference/list#post-1-lists-idlist-moveallcards
-      def move_list_cards(list_id, destination_list_id, board_id)
+      def move_list_cards(list_id, destination_list_id, board_id = nil)
+        board_id ||= resolve_board_id(destination_list_id)
         post list_path(list_id, camp("move_all_cards")),
-          list_id: destination_list_id, board_id: board_id
+          list_id: resource_id(destination_list_id), board_id: resource_id(board_id)
       end
 
       private
 
+      def resolve_board_id(list_id)
+        return list_id.board_id if list_id.respond_to?(:board_id)
+        return list_id.board.id if list_id.respond_to?(:board)
+
+        raise ArgumentError, "Required option :board_i"
+      end
+
       def list_resource(list_id, resource, *paths)
         paths, options = extract_options(camp(resource), *paths)
         get list_path(list_id, *paths), options

data/lib/tacokit/client/members.rb

@@ -1,94 +1,170 @@
 module Tacokit
   class Client
+    # Methods for the Members API
+    # @see https://developers.trello.com/advanced-reference/member
     module Members
-      # Retrieve a Trello member
-      #
+      # @overload member(username = "me", options = nil)
+      #   Retrieve a Trello member by username
+      #   @param username [String] the member's username
+      #   @param options [Hash] the options to fetch the member with
+      #   @return [Tacokit::Resource<Member>] the member resource
+      #   @example fetch the member named 'rossta'
+      #     Tacokit.member("tacokit") #=> Tacokit::Resource<Member>
+      # @overload member(options)
+      #   Retrieve the current member
+      #   @param options [Hash] the options to fetch the member with
+      #   @return [Tacokit::Resource<Member>] the member resource
+      #   @example fetch the current member
+      #     Tacokit.member #=> Tacokit::Resource<Member>
+      #   @example fetch the current member with all boards
+      #     Tacokit.member(boards: "all") #=> Tacokit::Resource<Member>
+      #   @example configure a local client and fetch different current member
+      #     client = Tacokit::Client.new app_key: "another-app-key"
+      #     client.member #=> Tacokit::Resource<Member>
       # @see https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username
       def member(username = "me", options = nil)
         username, options = extract_member_args(username, options)
         get member_path(username), options
       end
 
-      # Retrieve a member's actions
-      #
+      # @overload actions(username = "me", options = nil)
+      #   Retrieve a member's actions
+      #   @param username [String, Tacokit::Resource<Member>] the username or member resource
+      #   @param options [Hash] the options to fetch the actions with
+      #   @return [Tacokit::Collection<Action>] the actions collection
+      #   @example fetch the actions for the member named 'tacokit'
+      #     Tacokit.actions("tacokit") #=> Tacokit::Collection<Member>
+      # @overload actions(options = nil)
+      #   Retrieve the current member's actions
+      #   @param options [Hash] the options to fetch the actions with
+      #   @return [Tacokit::Collection] the action resources
+      #   @example fetch the current member's actions
+      #     Tacokit.actions #=> Tacokit::Collection<Action>
+      #   @example fetch the current member's card comment actions only
+      #     Tacokit.actions(filter: "comment_card") #=> Tacokit::Collection<Action>
       # @see https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username-actions
       def actions(username = "me", options = {})
         username, options = extract_member_args(username, options)
         paginated_get member_path(username, "actions"), options
       end
-      alias_method :member_actions, :actions
+      alias member_actions actions
 
-      # Retrieve a member's boards
-      #
+      # @overload boards(username = "me", options = {})
+      #   Retrieve a member's boards
+      #   @param username [String, Tacokit::Resource<Member>] the username or member resource
+      #   @param options [Hash] the options to fetch the boards with
+      #   @return [Tacokit::Collection<Board>] the boards collection
+      #   @example fetch the boards for the member named 'tacokit'
+      #     Tacokit.boards("tacokit") #=> Tacokit::Collection<Board>
+      # @overload boards(options = {})
+      #   Retrieve current member's boards
+      #   @param options [Hash] the options to fetch the boards with
+      #   @return [Tacokit::Resource] the boards collection
+      #   @example fetch the current member's boards
+      #     Tacokit.boards #=> Tacokit::Collection<Board>
+      #   @example fetch the current member's open boards only
+      #     Tacokit.boards(filter: "all") #=> Tacokit::Collection<Board>
       # @see https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username-boards
       def boards(username = "me", options = {})
         username, options = extract_member_args(username, options)
         get member_path(username, "boards"), options
       end
 
-      # Retrieve a member's cards
-      #
+      # @overload cards(username = "me", options = {})
+      #   Retrieve a member's cards
+      #   @param username [String, Tacokit::Resource<Member>] the username or member resource
+      #   @param options [Hash] the options to fetch the cards with
+      #   @return [Tacokit::Collection<Card>] the cards collection
+      #   @example fetch the cards for the member named 'tacokit'
+      #     Tacokit.cards("tacokit") #=> Tacokit::Collection<Card>
+      # @overload cards(options = {})
+      #   Retrieve current member's cards
+      #   @param options [Hash] the options to fetch the cards with
+      #   @return [Tacokit::Collection<Card>] the cards collection
+      #   @example fetch the current member's boards
+      #     Tacokit.cards #=> Tacokit::Collection<Card>
+      #   @example fetch the current member's closed cards only
+      #     Tacokit.cards(filter: "closed") #=> Tacokit::Collection<Card>
       # @see https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username-cards
       def cards(username = "me", options = {})
         username, options = extract_member_args(username, options)
         get member_path(username, "cards"), options
       end
 
-      # Retrieve a member's notifications
-      #
+      # @overload notifications(username = "me", options = {})
+      #   Retrieve a member's notifications
+      #   @param username [String, Tacokit::Resource<Member>] the username or member resource
+      #   @param options [Hash] the options to fetch the notifications with
+      #   @return [Tacokit::Collection<Notification>] the notifications collection
+      #   @example fetch the notifications for the member named 'tacokit'
+      #     Tacokit.notifications("tacokit") #=> Tacokit::Collection<Notification>
+      # @overload notifications(options = {})
+      #   Retrieve current member's notifications
+      #   @param options [Hash] the options to fetch the notifications with
+      #   @return [Tacokit::Collection<Notification>] the notifications collection
+      #   @example fetch the current member's boards
+      #     Tacokit.notifications #=> Tacokit::Collection<Notification>
+      #   @example fetch the current member's closed notifications only
+      #     Tacokit.notifications(filter: "closed") #=> Tacokit::Collection<Notification>
       # @see https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username-notifications
       def notifications(username = "me", options = {})
         username, options = extract_member_args(username, options)
         paginated_get member_path(username, "notifications"), options
       end
 
-      # Retrieve a member's organizations
-      #
+      # @overload organizations(username = "me", options = {})
+      #   Retrieve a member's organizations
+      #   @param username [String, Tacokit::Resource<Member>] the username or member resource
+      #   @param options [Hash] the options to fetch the organizations with
+      #   @return [Tacokit::Collection<Organization>] the organizations collection
+      #   @example fetch the current member's boards
+      #     Tacokit.organizations #=> Tacokit::Collection<Organization>
+      #   @example fetch the current member's closed organizations only
+      #     Tacokit.organizations(filter: "closed") #=> Tacokit::Collection<Organization>
+      # @overload organizations(options = {})
+      #   Retrieve current member's organizations
+      #   @param options [Hash] the options to fetch the organizations with
+      #   @return [Tacokit::Collection<Organization>] the organizations collection
+      #   @example fetch the organizations for the member named 'tacokit'
+      #     Tacokit.organizations("tacokit") #=> Tacokit::Collection<Organization>
       # @see https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username-organizations
       def organizations(username = "me", options = {})
         username, options = extract_member_args(username, options)
         get member_path(username, "organizations"), options
       end
 
-      # Retrieve a member's tokens
-      #
-      # @see https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username-tokens
+      # @overload tokens(username = "me", options = {})
+      #   Retrieve a member's tokens
+      #   @param username [String, Tacokit::Resource<Member>] the username or member resource
+      #   @param options [Hash] the options to fetch the tokens with
+      #   @return [Tacokit::Collection<Token>] the tokens collection
+      #   @example fetch the current member's boards
+      #     Tacokit.tokens #=> Tacokit::Collection<Token>
+      #   @example fetch the current member's closed tokens only
+      #     Tacokit.tokens(filter: "closed") #=> Tacokit::Collection<Token>
+      # @overload tokens(options = {})
+      #   Retrieve current member's tokens
+      #   @param options [Hash] the options to fetch the tokens with
+      #   @return [Tacokit::Collection<Token>] the tokens collection
+      #   @example fetch the tokens for the member named 'tacokit'
+      #     Tacokit.tokens("tacokit") #=> Tacokit::Collection<Token>
+      # @see https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username-organizations
       def tokens(username = "me", options = {})
         username, options = extract_member_args(username, options)
         get member_path(username, "tokens"), options
       end
 
       # Update a member
-      #
+      # @param username [String, Tacokit::Resource<Member>] the username or member resource
+      # @param options [Hash] the attributes to update on the list
+      # @example update current member's name
+      #   Tacokit.update_member(name: "Moonriver") #=> Tacokit::Resource<Member>
       # @see https://developers.trello.com/advanced-reference/member#put-1-members-idmember-or-username
-      def update_member(username, options = {})
+      def update_member(username = "me", options = {})
+        username, options = extract_member_args(username, options)
         put member_path(username), options
       end
 
-      # PUT /1/members/[idMember or username]/[field]
-      # avatarSource
-      # fullName
-      # initials
-      # username
-      # boardBackgrounds/[idBoardBackground]
-      # boardStars/[idBoardStar]
-      # boardStars/[idBoardStar]/idBoard
-      # boardStars/[idBoardStar]/pos
-      # customBoardBackgrounds/[idBoardBackground]
-      # prefs/colorBlind
-      # prefs/minutesBetweenSummaries
-      # savedSearches/[idSavedSearch]
-      # savedSearches/[idSavedSearch]/name
-      # savedSearches/[idSavedSearch]/pos
-      # savedSearches/[idSavedSearch]/query
-
-      # DELETE /1/members/[idMember or username]/[resource]/[resource_id]
-      # boardBackgrounds/[idBoardBackground]
-      # boardStars/[idBoardStar]
-      # customBoardBackgrounds/[idBoardBackground]
-      # customStickers/[idCustomSticker]
-      # savedSearches/[idSavedSearch]
-
       private
 
       def member_resource(username, resource, *paths)