monday_ruby 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e17b85396d9acd3d8dc9346a1c1b54f09280d8815941deee3ed952de6cf55ad1
-  data.tar.gz: 2bc9f14384736558a423f8690175a49dcf716746a2db1f5a5ef51cd7fefb0532
+  metadata.gz: b952365eaf332b933932dea993d33470bc585c9eadcf0dc7525e4550794313d2
+  data.tar.gz: 665a9d53d8a06972f88022040a28bf8003fa13247aa0bdac60e21f7ca8be9da5
 SHA512:
-  metadata.gz: d594d0addabe0adbb550ecf474e12c4d7645e10bdf37a9fe10c7b930ab63d954204c1658f30dd6258303c2b7c1e8fb6ace0476beb23fbf91fc864f9dfb4f6fe4
-  data.tar.gz: e42cdc2c6bcf6de3d5652e5bfa9c3d86f377155f0c2e06e76c2857b691341eca3e115e6abc8811fa02976afcda4997f8f3feffbc3f16b058bf4f3b9849c69835
+  metadata.gz: 2af82867a8586bb1bdd6f665f6e584b9e41ea76d0a74fab00f56d408d4357fee4986fde25df96403f0ba8284a4ecc99c61e97e1a4e9668e6024ca7e94574a22e
+  data.tar.gz: 7b66ffafb1c9bfd6bb5c24de9c19438acf89ba59a0a07204ca76a38e18bd043e183077ccda3042453560f71f18c307c73bf8b6f1d161e75a42a39bcadb468229

data/.rubocop.yml

@@ -16,3 +16,7 @@ Layout/LineLength:
 Metrics/BlockLength:
   Exclude:
     - "spec/**/*_spec.rb"
+
+Metrics/MethodLength:
+  Exclude:
+    - "lib/monday/util.rb"

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## v0.3.0 (July 10, 2023)
+
+### Added
+
+- Improved error handling
+- Support to configure the API version
+- Coverage report
+
 ## v0.2.0 (July 04, 2023)
 
 ### Added

data/README.md

@@ -2,6 +2,7 @@
 
 ![Build Status](https://github.com/sanifhimani/monday_ruby/actions/workflows/ci.yml/badge.svg)
 [![Gem Version](https://badge.fury.io/rb/monday_ruby.svg)](https://badge.fury.io/rb/monday_ruby)
+[![Coverage Status](https://coveralls.io/repos/github/sanifhimani/monday_ruby/badge.svg?branch=main)](https://coveralls.io/github/sanifhimani/monday_ruby?branch=main)
 
 This library provides convenient access to the monday.com API from the application written in the Ruby language.
 
@@ -9,6 +10,7 @@ The library provides:
 
 1. A pre-defined set of methods to easily interact with the API resources.
 2. Easy configuration path for fast setup and use.
+3. Easy error handling.
 
 **Visit https://monday-ruby.gitbook.io/docs/ for detailed documentation on how to use the library.**
 
@@ -68,6 +70,17 @@ require "monday_ruby"
 client = Monday::Client.new(token: "<AUTH_TOKEN>")
 ```
 
+You can optionally pass in the version of the API you want to use using the version configuration field. By default, the latest stable version is used.
+
+```ruby
+require "monday_ruby"
+
+Monday.configure do |config|
+  config.token = "<AUTH_TOKEN>"
+  config.version = "2023-07"
+end
+```
+
 ### Accessing a response object
 
 Get access to response objects by initializing a client and using the appropriate action you want to perform:

data/docs/README.md

@@ -6,6 +6,7 @@ The library provides:
 
 1. A pre-defined set of methods to easily interact with the API resources.
 2. Easy configuration path for fast setup and use.
+3. Easy error handling
 
 #### Requirements
 

data/docs/SUMMARY.md

@@ -6,6 +6,7 @@
 * [Client](client.md)
 * [Response](response.md)
 * [Quick Start](quick-start.md)
+* [Error Handling](error-handling.md)
 * [Resources](resources/README.md)
   * [Account](resources/account/README.md)
     * [#accounts](resources/account/accounts.md)

data/docs/configuration.md

@@ -26,3 +26,15 @@ require "monday_ruby"
 client = Monday::Client.new(token: <AUTH_TOKEN>)
 ```
 
+You can optionally pass in the version of the API you want to use using the `version` configuration field.
+
+By default, the latest stable version is used. Read more about the version on monday.com's [official documentation](https://developer.monday.com/api-reference/docs/api-versioning).
+
+```ruby
+require "monday_ruby"
+
+Monday.configure do |config|
+  config.token = <AUTH_TOKEN>
+  config.version = "2023-10"
+end
+```

data/docs/error-handling.md

@@ -0,0 +1,71 @@
+# Error Handling
+
+Monday.com has a set of predefined errors and exceptions that are sent back from their GraphQL API. Refer to their [official documentation](https://developer.monday.com/api-reference/docs/errors) to know more about the error codes.
+
+### Catching exceptions
+
+If there is an error from the API, the library raises an exception. It's a best practice to catch and handle exceptions.
+
+To catch an exception, use the `rescue` keyword. You can catch all the exceptions from the API using the `Monday::Error` class. However, it is recommended to catch specific exceptions using its subclasses and have a fallback rescue using `Monday::Error`.
+
+```ruby
+require "monday_ruby"
+
+client = Monday::Client.new(token: <AUTH_TOKEN>)
+
+def example
+  res = client.boards
+  puts res.body
+rescue Monday::AuthorizationError => error
+  puts "Authorization error: #{error.message}"
+  puts "Error code: #{error.code}"
+rescue Monday::Error => error
+  puts "Other error: #{error.message}"
+end
+```
+
+Along with the default status code exceptions, monday.com returns some other exceptions with `200` status code. This library handles those errors and raises exceptions accordingly.
+
+#### `Monday::InternalServer Error`
+
+This exception is raised when the server returns a `500` status code. Read more about what can cause this error on Monday.com's [official documentation](https://developer.monday.com/api-reference/docs/errors#internal-server-error).
+
+#### `Monday::AuthorizationError`
+
+This exception is raised when the server returns a `401` or a `403` status code. This can happen when the client is not authenticated, i.e., not configured with the token, or the token is incorrect.
+
+This exception is also raised when the server returns a `200` status code but the body returns `UserUnauthorizedException` error code.
+
+#### `Monday::RateLimitError`
+
+This exception is raised when the server returns a `429` status code. This can happen when you exceed the rate limit, i.e., 5,000 requests per minute. Read more about their rate limit on their [official documentation](https://developer.monday.com/api-reference/docs/rate-limits).
+
+#### `Monday::ResourceNotFoundError`
+
+This exception is raised when the server returns a `404` status code. This can happen when you pass an invalid ID in the query.
+
+This exception is also raised when the server returns a `200` status code but the body returns `ResourceNotFoundException` error code.
+
+#### `Monday::ComplexityError`
+
+This exception is raised when the server returns a `200` status code but the body returns  `ComplexityException` error code.
+
+#### `Monday::InvalidRequestError`
+
+This exception is raised when the server returns a `400` status code. This can happen when the query you pass is invalid.
+
+This exception is also raised when the server returns a `200` status code but the body returns the following error codes:
+
+1. `InvalidUserIdException`
+2. `InvalidVersionException`
+3. `InvalidColumnIdException`
+4. `InvalidItemIdException`
+5. `InvalidBoardIdException`
+6. `InvalidArgumentException`
+7. `CreateBoardException`
+8. `ItemsLimitationException`
+9. `ItemNameTooLongException`
+10. `ColumnValueException`
+11. `CorrectedValueException`
+
+Read more about these specific exceptions on their [official API documentation](https://developer.monday.com/api-reference/docs/errors).

data/lib/monday/client.rb

@@ -9,6 +9,7 @@ require_relative "request"
 require_relative "response"
 require_relative "resources"
 require_relative "util"
+require_relative "error"
 
 module Monday
   # Client executes requests against the monday.com's API and
@@ -30,7 +31,7 @@ module Monday
     def config_options(config_args)
       return Monday.config if config_args.empty?
 
-      Monday::Configuration.new(**config_args)
+      Configuration.new(**config_args)
     end
 
     def uri
@@ -45,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

@@ -10,10 +10,12 @@ module Monday
   class Configuration
     DEFAULT_HOST = "https://api.monday.com/v2"
     DEFAULT_TOKEN = nil
+    DEFAULT_VERSION = "2023-07"
 
     CONFIGURATION_FIELDS = %i[
       token
       host
+      version
     ].freeze
 
     attr_accessor(*CONFIGURATION_FIELDS)
@@ -24,6 +26,7 @@ module Monday
 
       @host = DEFAULT_HOST
       @token = DEFAULT_TOKEN
+      @version = DEFAULT_VERSION
 
       config_args.each do |key, value|
         public_send("#{key}=", value)
@@ -33,6 +36,7 @@ module Monday
     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.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monday_ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Sanif Himani
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-04 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:
@@ -30,6 +30,7 @@ files:
 - 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
@@ -66,6 +67,7 @@ files:
 - 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
@@ -85,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.2.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: []