camper 0.0.7 → 0.1.0

data/lib/camper.rb

@@ -6,7 +6,9 @@ require 'rack/oauth2'
 require 'camper/version'
 require 'camper/logging'
 require 'camper/error'
+require 'camper/recording_types'
 require 'camper/configuration'
+require 'camper/url_utils'
 require 'camper/authorization'
 require 'camper/resource'
 require 'camper/pagination_data'

data/lib/camper/api/comments.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Camper
+  class Client
+    # Defines methods related to comments.
+    # @see https://github.com/basecamp/bc3-api/blob/master/sections/comments.md
+    module CommentsAPI
+      # Get a paginated list of active comments for a given resource
+      #
+      # @example
+      #   client.comments(todo)
+      #
+      # @param resource [Resource] resource to gets the comments from
+      # @return [PaginatedResponse<Resource>]
+      # @raise [Error::ResourceCannotBeCommented] if the resource doesn't support comments
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/comments.md#get-comments
+      def comments(resource)
+        raise Error::ResourceCannotBeCommented, resource unless resource.can_be_commented?
+
+        get(resource.comments_url, override_path: true)
+      end
+
+      # Get a comment within a resource
+      #
+      # @example
+      #   client.comment(todo, 10)
+      # @example
+      #   client.comment(my_message, '23')
+      #
+      # @param resource [Resource] resource to get the comment from
+      # @param comment_id [Integer|String] id of comment ot retrieve
+      # @return [Resource]
+      # @raise [Error::ResourceCannotBeCommented] if the resource doesn't support comments
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/comments.md#get-a-comment
+      def comment(resource, comment_id)
+        raise Error::ResourceCannotBeCommented, resource unless resource.can_be_commented?
+
+        bucket_id = resource.bucket.id
+
+        get("/buckets/#{bucket_id}/comments/#{comment_id}")
+      end
+
+      # Create a new comment for a given resource
+      #
+      # @example
+      #   client.create_comment(my_message, 'We are ready to start the project')
+      #
+      # @param resource [Resource] resource to create the comment on
+      # @param content [String] content of the comment
+      # @return [Resource]
+      # @raise [Error::ResourceCannotBeCommented] if the resource doesn't support comments
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/comments.md#create-a-comment
+      def create_comment(resource, content)
+        raise Error::ResourceCannotBeCommented, resource unless resource.can_be_commented?
+
+        post(resource.comments_url, override_path: true, body: { content: content })
+      end
+
+      # Update the content in a comment
+      #
+      # @example
+      #   client.update_comment(comment, 'Fixed grammar mistakes')
+      #
+      # @param comment [Resource] comment to modify
+      # @param content [String] new content of the comment
+      # @return [Resource]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/comments.md#update-a-comment
+      def update_comment(comment, content)
+        bucket_id = comment.bucket.id
+
+        put("/buckets/#{bucket_id}/comments/#{comment.id}", body: { content: content })
+      end
+
+      # Trash a comment
+      #   it calls the trash_recording endpoint under the hood
+      #
+      # @example
+      #   client.trash_comment(current_comment)
+      #
+      # @param comment [Resource] the comment to be trashed
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/recordings.md#trash-a-recording
+      def trash_comment(comment)
+        trash_recording(comment)
+      end
+    end
+  end
+end

data/lib/camper/api/message_board.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Camper
+  class Client
+    # Defines methods related to message boards.
+    # @see https://github.com/basecamp/bc3-api/blob/master/sections/message_boards.md
+    module MessageBoardsAPI
+      # Get a message board for a given project
+      #
+      # @example
+      #   client.message_board(project)
+      #
+      # @param project [Project] project to get the associated message board on
+      # @return [Resource]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/message_boards.md#message-boards
+      def message_board(project)
+        board = project.message_board
+
+        get(board.url, override_path: true)
+      end
+    end
+  end
+end

data/lib/camper/api/message_types.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Camper
+  class Client
+    # Defines methods related to message types.
+    # @see https://github.com/basecamp/bc3-api/blob/master/sections/message_types.md
+    module MessageTypesAPI
+      # Get a paginated list of all messages types in a given project
+      #
+      # @example
+      #   client.messages_types(my_project)
+      #
+      # @param project [Project] project to get the messages types from
+      # @return [PaginatedResponse<Resource>]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/message_types.md#get-message-types
+      def message_types(project)
+        get("/buckets/#{project.id}/categories")
+      end
+
+      # Get a messages type in a given project
+      #
+      # @example
+      #   client.message_type(my_project, '10')
+      # @example
+      #   client.message_type(my_project, 64926)
+      #
+      # @param project [Project] project to get the messages type from
+      # @param message_type_id [Integer|String] id of the message type to retrieve
+      # @return [Resource]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/message_types.md#get-a-message-type
+      def message_type(project, message_type_id)
+        get("/buckets/#{project.id}/categories/#{message_type_id}")
+      end
+
+      # Create a messages type in a given project
+      #
+      # @example
+      #   client.create_message_type(my_project, 'Farewell', '👋')
+      #
+      # @param project [Project] project where the message type belongs to
+      # @param name [String] name of the new message type
+      # @param icon [String] icon to associate with the new message type
+      # @return [Resource]
+      # @raise [Error::InvalidParameter] if either name or icon is blank
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/message_types.md#create-a-message-type
+      def create_message_type(project, name, icon)
+        raise Error::InvalidParameter, 'Name and icon parameters cannot be blank' if name.blank? || icon.blank?
+
+        post("/buckets/#{project.id}/categories", body: { name: name, icon: icon })
+      end
+
+      # Update a message type in a given project
+      #
+      # @example
+      #   client.update_message_type(my_project, type, name: 'Quick Update')
+      # @example
+      #   client.update_message_type(my_project, type, icon: '🤙')
+      #
+      # @param project [Project] project where the message type belongs to
+      # @param type [Resource|Integer|String] resource or id representing a message type
+      # @param options [Hash] hash containing the name and/or icon to modify
+      # @return [Resource]
+      # @raise [Error::InvalidParameter] if options parameter is empty
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/message_types.md#destroy-a-message-type
+      def update_message_type(project, type, options = {})
+        raise Error::InvalidParameter, 'options cannot be empty' if options.empty?
+
+        type_id = type.respond_to?(:id) ? type.id : type
+
+        put("/buckets/#{project.id}/categories/#{type_id}", body: options)
+      end
+
+      # Delete a message type in a given project
+      #
+      # @example
+      #   client.delete_message_type(my_project, type)
+      #
+      # @param project [Project] project where the message type belongs to
+      # @param type [Resource|Integer|String] resource or id representing a message type
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/message_types.md#destroy-a-message-type
+      def delete_message_type(project, type)
+        type_id = type.respond_to?(:id) ? type.id : type
+
+        delete("/buckets/#{project.id}/categories/#{type_id}")
+      end
+
+      alias trash_message_type delete_message_type
+    end
+  end
+end

data/lib/camper/api/messages.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Camper
+  class Client
+    # Defines methods related to messages.
+    # @see https://github.com/basecamp/bc3-api/blob/master/sections/messages.md
+    module MessagesAPI
+      # Get a paginated list of active messages under the given message board or project
+      #
+      # @example
+      #   client.messages(message_board)
+      # @example
+      #   client.messages(my_project)
+      #
+      # @param parent [Project|Resource] either a project or message board resource
+      # @return [PaginatedResponse<Resource>]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/messages.md#get-messages
+      def messages(parent)
+        if parent.is_a?(Project)
+          bucket_id, board_id = parent.id, parent.message_board.id
+        else
+          bucket_id, board_id = parent.bucket.id, parent.id
+        end
+
+        get("/buckets/#{bucket_id}/message_boards/#{board_id}/messages")
+      end
+
+      # Get a paginated list of active messages under the given message board or project
+      #
+      # @example
+      #   client.message(my_project, '2343')
+      # @example
+      #   client.message(message_board, 234)
+      #
+      # @param parent [Project|Resource] either a project or message board resource
+      # @param message_id [Integer|String] id of the message to retrieve
+      # @return [Resource]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/messages.md#get-a-message
+      def message(parent, message_id)
+        bucket_id = parent.is_a?(Project) ? parent.id : parent.bucket.id
+
+        get("/buckets/#{bucket_id}/messages/#{message_id}")
+      end
+
+      # Create a message
+      #
+      # @example
+      #   client.create_message(my_project, 'New Infrastructure')
+      # @example
+      #   client.create_message(message_board, 'New Launch',
+      #     content: 'This launch will be awesome',
+      #     category_id: '23'
+      #   )
+      #
+      # @param parent [Project|Resource] either a project or message board resource
+      # @param subject [String] subject of the new message
+      # @param options [Hash] hash containing the content and/or category id for the new message
+      # @return [Resource]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/messages.md#create-a-message
+      def create_message(parent, subject, options = {})
+        if parent.is_a?(Project)
+          bucket_id, board_id = parent.id, parent.message_board.id
+        else
+          bucket_id, board_id = parent.bucket.id, parent.id
+        end
+
+        post(
+          "/buckets/#{bucket_id}/message_boards/#{board_id}/messages",
+          body: options.merge({ subject: subject, status: 'active' })
+        )
+      end
+
+      # Update a message
+      #
+      # @example
+      #   client.update_message(message, subject: 'New Infrastructure')
+      # @example
+      #   client.update_message(message, content: 'This launch will be awesome')
+      # @example
+      #   client.update_message(message, category_id: '6918641') # message type id
+      #
+      # @param message [Resource] message to update
+      # @param options [Hash] subject of the new message
+      # @param options [Hash] hash containing subject, content and/or category_id to update
+      # @return [Resource]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/messages.md#update-a-message
+      def update_message(message, options = {})
+        raise Error::InvalidParameter, 'options cannot be empty' if options.empty?
+
+        update("/buckets/#{message.bucket.id}/messages/#{message.id}", body: options)
+      end
+
+      # Trash message
+      #   it calls the trash_recording endpoint under the hood
+      #
+      # @example
+      #   client.trash_message(message)
+      #
+      # @param todo [Resource] the message to be trashed
+      # @raise [Error::InvalidParameter] if url field in todo param
+      #   is not a valid basecamp url
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/recordings.md#trash-a-recording
+      def trash_message(message)
+        trash_recording(message)
+      end
+    end
+  end
+end

data/lib/camper/api/people.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Camper
+  class Client
+    # Defines methods related to people.
+    # @see https://github.com/basecamp/bc3-api/blob/master/sections/people.md
+    module PeopleAPI
+      # Get all people visible to the current user
+      #
+      # @example
+      #   client.people
+      #
+      # @return [PaginatedResponse<Resource>]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/people.md#get-all-people
+      def people
+        get('/people')
+      end
+
+      # Get all active people on the project with the given ID
+      #
+      # @example
+      #   client.people_in_project(10)
+      # @example
+      #   client.people_in_project("20")
+      # @example
+      #   client.people_in_project(my_project)
+      #
+      # @param project [Resource|Integer|String] A project resource or a project id
+      # @return [PaginatedResponse<Resource>]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/people.md#get-people-on-a-project
+      def people_in_project(project)
+        id = project.respond_to?(:id) ? project.id : project
+
+        get("/projects/#{id}/people")
+      end
+
+      # Allows granting new and existing people access to a project, and revoking access from existing people.
+      #
+      # @example
+      #   client.update_access_in_project(10, { grant: [102, 127] })
+      # @example
+      #   client.update_access_in_project("8634", { revoke: [300, 12527] })
+      # @example
+      #   client.update_access_in_project(my_project, {
+      #     create: [{
+      #       name: "Victor Copper",
+      #       email_address: "victor@hanchodesign.com"
+      #     }]
+      #   })
+      #
+      # @param project [Resource|Integer|String] A project resource or a project id
+      # @param options [Hash] options to update access, either grant, revoke or create new people
+      # @return [Resource]
+      # @raise [Error::InvalidParameter] if no option is specified
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/people.md#update-who-can-access-a-project
+      def update_access_in_project(project, options = {})
+        raise Camper::Error::InvalidParameter, 'options cannot be empty' if options.empty?
+
+        id = project.respond_to?(:id) ? project.id : project
+
+        put("/projects/#{id}/people/users", body: { **options })
+      end
+
+      # Get all people on this Basecamp account who can be pinged
+      #
+      # @example
+      #   client.pingable_people
+      #
+      # @return [PaginatedResponse<Resource>]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/people.md#get-pingable-people
+      def pingable_people
+        get('/circles/people')
+      end
+
+      # Get the profile for the user with the given ID
+      #
+      # @example
+      #   client.person(234790)
+      #
+      # @param id [Integer|String] A user id
+      # @return [Resource]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/people.md#get-person
+      def person(id)
+        get("/people/#{id}")
+      end
+
+      # Get the current user's personal info.
+      #
+      # @example
+      #   client.profile
+      #
+      # @return [Resource]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/people.md#get-my-personal-info
+      def profile
+        get('/my/profile')
+      end
+    end
+  end
+end

data/lib/camper/api/projects.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Camper
+  class Client
+    # Defines methods related to projects.
+    # @see https://github.com/basecamp/bc3-api/blob/master/sections/projects.md
+    module ProjectsAPI
+      # Get the projects visible to the current user
+      #
+      # @example
+      #   client.projects
+      # @example
+      #   client.projects(status: 'trashed')
+      #
+      # @param options [Hash] extra options to filter the list of todolist
+      # @return [PaginatedResponse<Project>]
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#get-all-projects
+      def projects(options = {})
+        get('/projects', query: options)
+      end
+
+      # Get a project with a given id, granted they have access to it
+      #
+      # @example
+      #   client.project(82564)
+      # @example
+      #   client.project('7364183')
+      #
+      # @param id [Integet|String] id of the project to retrieve
+      # @return [Project]
+      # @raise [Error::InvalidParameter] if id is blank (nil or empty string)
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#get-a-project
+      def project(id)
+        raise Error::InvalidParameter, id if id.blank?
+
+        get("/projects/#{id}")
+      end
+
+      # Create a project
+      #
+      # @example
+      #   client.create_project("Marketing Campaign")
+      # @example
+      #   client.create_project('Better Marketing Campaign', "For Client: XYZ")
+      #
+      # @param name [String] name of the project to create
+      # @param description [String] description of the project
+      # @return [Project]
+      # @raise [Error::InvalidParameter] if name is blank (nil or empty string)
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#create-a-project
+      def create_project(name, description = '')
+        raise Error::InvalidParameter, name if name.blank?
+
+        post('/projects', body: { name: name, description: description })
+      end
+
+      # Update a project
+      #  description can be set to empty by passing an empty string
+      #
+      # @example
+      #   client.update_project(12324, name: 'Retros')
+      # @example
+      #   client.update_project('157432', description: 'A new description')
+      # @example
+      #   client.update_project('157432', description: '')
+      # @example
+      #   client.update_project(my_project, name: 'A new name', description: 'A new description')
+      #
+      # @param project [Integer|String|Project] either a project object or a project id
+      # @param name [String] optional new name of the project
+      # @param description [String] optinal new description of the project
+      # @return [Project]
+      # @raise [Error::InvalidParameter] if both name and description are blank (nil or empty strings)
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#update-a-project
+      def update_project(project, name: '', description: nil)
+        # rubocop:disable Style/IfUnlessModifier:
+        if name.blank? && description.blank?
+          raise Error::InvalidParameter, 'name and description cannot both be blank'
+        end
+
+        # rubocop:enable Style/IfUnlessModifier
+
+        id = project.respond_to?(:id) ? project.id : project
+
+        options = {}
+        options[:name] = name unless name.blank?
+        options[:description] = description unless description.nil?
+
+        put("/projects/#{id}", body: { **options })
+      end
+
+      # Delete a project
+      #
+      # @example
+      #   client.delete_project(12324)
+      # @example
+      #   client.delete_project('157432')
+      # @example
+      #   client.delete_project(my_project)
+      #
+      # @param project [Integer|String|Project] either a project object or a project id
+      # @raise [Error::InvalidParameter] if project param is blank
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#trash-a-project
+      def delete_project(project)
+        raise Error::InvalidParameter, 'project cannot be blank' if project.blank?
+
+        id = project.respond_to?(:id) ? project.id : project
+
+        delete("/projects/#{id}")
+      end
+
+      alias trash_project delete_project
+
+      def todoset(project)
+        todoset = project.todoset
+        get(todoset.url, override_path: true)
+      end
+    end
+  end
+end