monday_ruby 0.1.0 → 0.3.0

data/docs/resources/item/duplicate_item.md

@@ -0,0 +1,87 @@
+# #duplicate\_item
+
+The `duplicate_item` mutation will allow you to duplicate an item.
+
+### Basic usage
+
+This method accepts three required arguments - `board_id`, `item_id` and `with_updates`.
+
+{% code lineNumbers="true" %}
+```ruby
+client = Monday::Client.new(token: <AUTH_TOKEN>)
+
+board_id = "123"
+item_id = "7890"
+with_updates = true
+response = client.duplicate_item(board_id, item_id, with_updates)
+
+puts response.body
+```
+{% endcode %}
+
+This will return the items' ID, name and created\_at fields by default.
+
+The response body from the above query would be as follows:
+
+{% code lineNumbers="true" %}
+```json
+{
+  "data": {
+    "duplicate_item": {
+      "id": "0123",
+      "name": "New Task (copy)",
+      "created_at": "2023-06-27T16:45:07Z"
+    }
+  },
+  "account_id": 123
+}
+```
+{% endcode %}
+
+### Customizing fields to retrieve
+
+You can customize the fields to retrieve by passing in the `select` option and listing all the fields you need to retrieve as an array.
+
+{% code lineNumbers="true" %}
+```ruby
+client = Monday::Client.new(token: <AUTH_TOKEN>)
+
+board_id = "123"
+item_id = "7890"
+with_updates = true
+
+select = %w[id state creator_id]
+response = client.duplicate_item(board_id, item_id, with_updates, select: select)
+
+puts response.body
+```
+{% endcode %}
+
+### Retrieving nested fields
+
+Some fields have nested attributes, and you need to specify the attributes to retrieve that field; else, the API will respond with an error. For example, the field `creator` is of type `User` and expects you to pass the attributes from `User` that you want to retrieve for `creator`.
+
+{% code lineNumbers="true" %}
+```ruby
+client = Monday::Client.new(token: <AUTH_TOKEN>)
+
+board_id = "123"
+item_id = "7890"
+with_updates = true
+
+select = [
+  "id",
+  "state",
+  "creator_id",
+  {
+    creator: %w[id name email is_admin]
+  }
+]
+
+response = client.duplicate_item(board_id, item_id, with_updates, select: select)
+
+puts response.body
+```
+{% endcode %}
+
+You can find the list of all the available fields for items [here](https://developer.monday.com/api-reference/docs/items#fields).

data/docs/resources/item/items.md

@@ -0,0 +1,95 @@
+# #items
+
+Querying `items` will return the metadata for one or a collection of columns.
+
+### Basic usage
+
+This method accepts various arguments to fetch the items. You can find the complete list of arguments [here](https://developer.monday.com/api-reference/docs/items#arguments).
+
+You can pass these filters using the `args` option.
+
+{% code lineNumbers="true" %}
+```ruby
+client = Monday::Client.new(token: <AUTH_TOKEN>)
+
+args = {
+  ids: [1234, 5678]
+}
+response = client.items(args: args)
+
+puts response.body
+```
+{% endcode %}
+
+This will return the items' ID, name and created\_at fields by default.
+
+The response body from the above query would be as follows:
+
+{% code lineNumbers="true" %}
+```json
+{
+  "data": {
+    "items": [
+      {
+        "id": "1234",
+        "name": "Task 1",
+        "created_at": "2023-06-26T23:20:56Z"
+      },
+      "items": [
+      {
+        "id": "5678",
+        "name": "Task 2",
+        "created_at": "2023-06-26T23:25:50Z"
+      }
+    ]
+  },
+  "account_id": 123
+}
+```
+{% endcode %}
+
+### Customizing fields to retrieve
+
+You can customize the fields to retrieve by passing in the `select` option and listing all the fields you need to retrieve as an array.
+
+{% code lineNumbers="true" %}
+```ruby
+client = Monday::Client.new(token: <AUTH_TOKEN>)
+
+args = {
+  ids: [1234, 5678]
+}
+select = %w[id state creator_id]
+response = client.items(args: args, select: select)
+
+puts response.body
+```
+{% endcode %}
+
+### Retrieving nested fields
+
+Some fields have nested attributes, and you need to specify the attributes to retrieve that field; else, the API will respond with an error. For example, the field `creator` is of type `User` and expects you to pass the attributes from `User` that you want to retrieve for `creator`.
+
+{% code lineNumbers="true" %}
+```ruby
+client = Monday::Client.new(token: <AUTH_TOKEN>)
+
+args = {
+  ids: [1234, 5678]
+}
+select = [
+  "id",
+  "state",
+  "creator_id",
+  {
+    creator: %w[id name email is_admin]
+  }
+]
+
+response = client.items(args: args, select: select)
+
+puts response.body
+```
+{% endcode %}
+
+You can find the list of all the available fields for items [here](https://developer.monday.com/api-reference/docs/items#fields).

data/docs/response.md

@@ -0,0 +1,21 @@
+# Response
+
+Every request made using the client will return a `Monday::Response` object. This object consists of the following methods:
+
+#### `status`
+
+This is the returned HTTP status code.
+
+#### `body`
+
+This is the response body.
+
+#### `headers`
+
+This is the response header.
+
+#### `success?`
+
+This returns true or false based on the status code and the response body.
+
+Sometimes when the application handles the exceptions, the API will return a `200` status code, but the body will return the error message.

data/lib/monday/client.rb

@@ -9,9 +9,10 @@ require_relative "request"
 require_relative "response"
 require_relative "resources"
 require_relative "util"
+require_relative "error"
 
 module Monday
-  # Client executes requests against the Monday.com API and
+  # Client executes requests against the monday.com's API and
   # allows a user to mutate and retrieve resources.
   class Client
     include Resources
@@ -19,19 +20,20 @@ module Monday
     JSON_CONTENT_TYPE = "application/json"
     private_constant :JSON_CONTENT_TYPE
 
-    Monday::Configuration::CONFIGURATION_FIELDS.each do |config_key|
-      define_method(config_key) do
-        @config.public_send(config_key)
-      end
-    end
+    attr_reader :config
 
     def initialize(config_args = {})
-      @config = Monday::Configuration.new(**config_args)
-      yield(@config) if block_given?
+      @config = config_options(config_args)
     end
 
     private
 
+    def config_options(config_args)
+      return Monday.config if config_args.empty?
+
+      Configuration.new(**config_args)
+    end
+
     def uri
       URI(@config.host)
     end
@@ -44,8 +46,34 @@ module Monday
     end
 
     def make_request(body)
-      response = Monday::Request.post(uri, body, request_headers)
-      Monday::Response.new(response)
+      response = Request.post(uri, body, request_headers)
+
+      handle_response(Response.new(response))
+    end
+
+    def handle_response(response)
+      return response if response.success?
+
+      raise_errors(response)
+    end
+
+    def raise_errors(response)
+      raise default_exception(response) unless (200..299).cover?(response.status)
+
+      raise response_exception(response)
+    end
+
+    def response_exception(response)
+      error_code = response.body["error_code"]
+
+      return Error.new(response: response) if error_code.nil?
+
+      exception_klass, code = Util.response_error_exceptions_mapping(error_code)
+      exception_klass.new(message: error_code, response: response, code: code)
+    end
+
+    def default_exception(response)
+      Util.status_code_exceptions_mapping(response.status).new(response: response)
     end
   end
 end

data/lib/monday/configuration.rb

@@ -9,11 +9,13 @@ module Monday
   # host: defaults to https://api.monday.com/v2
   class Configuration
     DEFAULT_HOST = "https://api.monday.com/v2"
-    private_constant :DEFAULT_HOST
+    DEFAULT_TOKEN = nil
+    DEFAULT_VERSION = "2023-07"
 
     CONFIGURATION_FIELDS = %i[
       token
       host
+      version
     ].freeze
 
     attr_accessor(*CONFIGURATION_FIELDS)
@@ -23,10 +25,18 @@ module Monday
       raise ArgumentError, "Unknown arguments: #{invalid_keys}" unless invalid_keys.empty?
 
       @host = DEFAULT_HOST
+      @token = DEFAULT_TOKEN
+      @version = DEFAULT_VERSION
 
       config_args.each do |key, value|
         public_send("#{key}=", value)
       end
     end
+
+    def reset
+      @token = DEFAULT_TOKEN
+      @host = DEFAULT_HOST
+      @version = DEFAULT_VERSION
+    end
   end
 end

data/lib/monday/error.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Monday
+  # Monday::Error is the base error class from which other
+  # specific error classes are derived.
+  class Error < StandardError
+    attr_reader :response, :message, :code
+
+    def initialize(message: nil, response: nil, code: nil)
+      @response = response
+      @message = error_message(message)
+      @code = error_code(code)
+
+      super(@message)
+    end
+
+    def error_data
+      return {} if response&.body&.dig("error_data").nil?
+
+      response.body["error_data"]
+    end
+
+    private
+
+    def error_code(code)
+      return code unless code.nil?
+
+      response_error_code.nil? ? response&.status : response_error_code
+    end
+
+    def error_message(message)
+      return response_error_message if message.nil?
+      return message if response_error_message.nil?
+
+      "#{message}: #{response_error_message}"
+    end
+
+    def response_error_code
+      return if response.nil?
+
+      response.body["status_code"]
+    end
+
+    def response_error_message
+      return if response.nil?
+
+      response.body["error_message"].nil? ? response.body["errors"].to_s : response.body["error_message"].to_s
+    end
+  end
+
+  # InternalServerError is raised when the request returns
+  # a 500 status code.
+  class InternalServerError < Error
+  end
+
+  # AuthorizationError is raised when the request returns
+  # a 401 or 403 status code.
+  #
+  # It is also raised when the body returns the following error_code:
+  #   UserUnauthorizedException
+  class AuthorizationError < Error
+  end
+
+  # RateLimitError is raised when the request returns
+  # a 429 status code.
+  class RateLimitError < Error
+  end
+
+  # ResourceNotFoundError is raised when the request returns
+  # a 404 status code.
+  #
+  # It is also raised when the body returns the following error_code:
+  #   ResourceNotFoundException
+  class ResourceNotFoundError < Error
+  end
+
+  # ResourceNotFoundError is raised when the request returns
+  # a 400 status code.
+  #
+  # It is also raised when the body returns the following error_codes:
+  #   InvalidUserIdException, InvalidVersionException, InvalidColumnIdException
+  #   InvalidItemIdException, InvalidBoardIdException, InvalidArgumentException
+  #   CreateBoardException, ItemsLimitationException, ItemNameTooLongException
+  #   ColumnValueException, CorrectedValueException
+  class InvalidRequestError < Error
+  end
+
+  # ComplexityError is raised when the body returns the following error_code:
+  #   ComplexityException
+  class ComplexityError < Error
+  end
+end

data/lib/monday/response.rb

@@ -6,6 +6,9 @@ module Monday
   #
   # Returns status code, parsed body and headers.
   class Response
+    ERROR_OBJECT_KEYS = %w[errors error_code error_message].freeze
+    private_constant :ERROR_OBJECT_KEYS
+
     attr_reader :status, :body, :headers
 
     def initialize(response)
@@ -26,7 +29,7 @@ module Monday
     attr_reader :response
 
     def errors?
-      parse_body.key?("errors") || parse_body.key?("error_message")
+      (parse_body.keys & ERROR_OBJECT_KEYS).any?
     end
 
     def parse_body

data/lib/monday/util.rb

@@ -25,6 +25,36 @@ module Monday
         values
       end
 
+      def status_code_exceptions_mapping(status_code)
+        {
+          "500" => InternalServerError,
+          "429" => RateLimitError,
+          "404" => ResourceNotFoundError,
+          "403" => AuthorizationError,
+          "401" => AuthorizationError,
+          "400" => InvalidRequestError
+        }[status_code.to_s] || Error
+      end
+
+      def response_error_exceptions_mapping(error_code)
+        {
+          "ComplexityException" => [ComplexityError, 429],
+          "UserUnauthorizedException" => [AuthorizationError, 403],
+          "ResourceNotFoundException" => [ResourceNotFoundError, 404],
+          "InvalidUserIdException" => [InvalidRequestError, 400],
+          "InvalidVersionException" => [InvalidRequestError, 400],
+          "InvalidColumnIdException" => [InvalidRequestError, 400],
+          "InvalidItemIdException" => [InvalidRequestError, 400],
+          "InvalidBoardIdException" => [InvalidRequestError, 400],
+          "InvalidArgumentException" => [InvalidRequestError, 400],
+          "CreateBoardException" => [InvalidRequestError, 400],
+          "ItemsLimitationException" => [InvalidRequestError, 400],
+          "ItemNameTooLongException" => [InvalidRequestError, 400],
+          "ColumnValueException" => [InvalidRequestError, 400],
+          "CorrectedValueException" => [InvalidRequestError, 400]
+        }[error_code] || [Error, 400]
+      end
+
       private
 
       def format_array(array)

data/lib/monday/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Monday
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/monday_ruby.rb

@@ -2,3 +2,16 @@
 
 require_relative "monday/client"
 require_relative "monday/version"
+
+# Module to configure the library globally
+module Monday
+  module_function
+
+  def configure
+    yield config
+  end
+
+  def config
+    @config ||= Configuration.new
+  end
+end

data/monday_ruby.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   spec.description = "A Gem to easily interact with monday.com API using native Ruby"
   spec.homepage = repository
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.6.0"
+  spec.required_ruby_version = ">= 2.7.0"
 
   spec.metadata = {
     "homepage_uri" => spec.homepage,
@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
       (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git Gemfile])
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monday_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Sanif Himani
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-06-28 00:00:00.000000000 Z
+date: 2023-07-10 00:00:00.000000000 Z
 dependencies: []
 description: A Gem to easily interact with monday.com API using native Ruby
 email:
@@ -17,6 +17,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".env"
 - ".rspec"
 - ".rubocop.yml"
 - ".vscode/settings.json"
@@ -25,8 +26,48 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- docs/README.md
+- docs/SUMMARY.md
+- docs/client.md
+- docs/configuration.md
+- docs/error-handling.md
+- docs/getting-started.md
+- docs/quick-start.md
+- docs/resources/README.md
+- docs/resources/account/README.md
+- docs/resources/account/accounts.md
+- docs/resources/activity-log/README.md
+- docs/resources/activity-log/activity_logs.md
+- docs/resources/board-view/README.md
+- docs/resources/board-view/board_views.md
+- docs/resources/board/README.md
+- docs/resources/board/archive_board.md
+- docs/resources/board/boards.md
+- docs/resources/board/create_board.md
+- docs/resources/board/delete_board.md
+- docs/resources/board/delete_board_subscribers.md
+- docs/resources/board/duplicate_board.md
+- docs/resources/board/update_board.md
+- docs/resources/column/README.md
+- docs/resources/column/change_column_metadata.md
+- docs/resources/column/change_column_title.md
+- docs/resources/column/change_column_value.md
+- docs/resources/column/change_multiple_column_value.md
+- docs/resources/column/change_simple_column_value.md
+- docs/resources/column/column_values.md
+- docs/resources/column/columns.md
+- docs/resources/column/create_column.md
+- docs/resources/column/delete_column.md
+- docs/resources/item/README.md
+- docs/resources/item/archive_item.md
+- docs/resources/item/create_item.md
+- docs/resources/item/delete_item.md
+- docs/resources/item/duplicate_item.md
+- docs/resources/item/items.md
+- docs/response.md
 - lib/monday/client.rb
 - lib/monday/configuration.rb
+- lib/monday/error.rb
 - lib/monday/request.rb
 - lib/monday/resources.rb
 - lib/monday/resources/account.rb
@@ -46,7 +87,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/sanifhimani/monday_ruby
   documentation_uri: https://monday-ruby.gitbook.io/docs/
-  changelog_uri: https://github.com/sanifhimani/monday_ruby/blob/v0.1.0/CHANGELOG.md
+  changelog_uri: https://github.com/sanifhimani/monday_ruby/blob/v0.3.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -56,7 +97,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="