monday_ruby 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e17b85396d9acd3d8dc9346a1c1b54f09280d8815941deee3ed952de6cf55ad1
-  data.tar.gz: 2bc9f14384736558a423f8690175a49dcf716746a2db1f5a5ef51cd7fefb0532
+  metadata.gz: 6f0e71a61ef39a418ca03c8151a357e3623f9c4a030c74cee613e4cefc8d684a
+  data.tar.gz: 2ab39c2856f63b1e72a9395630c43b92fd589b1790954b36791ed105f6e52362
 SHA512:
-  metadata.gz: d594d0addabe0adbb550ecf474e12c4d7645e10bdf37a9fe10c7b930ab63d954204c1658f30dd6258303c2b7c1e8fb6ace0476beb23fbf91fc864f9dfb4f6fe4
-  data.tar.gz: e42cdc2c6bcf6de3d5652e5bfa9c3d86f377155f0c2e06e76c2857b691341eca3e115e6abc8811fa02976afcda4997f8f3feffbc3f16b058bf4f3b9849c69835
+  metadata.gz: 65ad4b3eec9937e42fe5a2a811f7ccdc2caf3c17e4b38ede2b10a7be148519ec6a7e75d5b272fb86c33667be7309b2c51858f7e97563f147ca1f35d9adca1ac9
+  data.tar.gz: 41c14a6bd4c846d25701a19a7dadb775e379ac2a45b1967b3d97025301dfb1ccdbc5983c4efa6d78769f9daedfb9d3a9773fa976140816017d97308f128b4814

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,17 @@
+## v0.4.0 (September 15, 2023)
+
+### Added
+
+- Support for Reading, Creating and Deleting Workspaces
+
+## 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/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+Thanks for taking the time to contribute!
+
+The following is a set of guidelines for contributing to `monday_ruby`. These are mostly guidelines, not rules. Use your best judgment, and feel to propose changes to this document in a pull request.
+
+## Your first code contribution
+
+Unsure where to begin contributing? You can start by looking through `good first issue` and `help wanted` issues.
+
+### Pull request
+
+Please follow these steps to have your contribution considered:
+
+1. Follow the [pull request template](PULL_REQUEST_TEMPLATE.md).
+2. Follow the [commit guidelines](#commit-message-guidelines).
+3. After you submit your pull request, verify that all the status checks are passing.
+
+## Commit message guidelines
+
+* Use present tense ("Add feature" not "Added feature")
+* Use the imperative mood ("Move file to..." not "Moves file to...")
+* Limit the first line to 70 characters or less.
+* Reference issues and pull requests after the first line.
+* Try to follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)

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-07"
+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/resources/workspace.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Monday
+  module Resources
+    # Represents Monday.com's workspace resource.
+    module Workspace
+      DEFAULT_SELECT = %w[id name description].freeze
+
+      # Retrieves all the workspaces.
+      #
+      # Allows filtering workspaces using the args option.
+      # Allows customizing the values to retrieve using the select option.
+      # By default, ID, name and description fields are retrieved.
+      def workspaces(args: {}, select: DEFAULT_SELECT)
+        query = "query { workspaces(#{Util.format_args(args)}) {#{Util.format_select(select)}}}"
+
+        make_request(query)
+      end
+
+      # Creates a new workspaces.
+      #
+      # Allows customizing creating a workspace using the args option.
+      # Allows customizing the values to retrieve using the select option.
+      # By default, ID, name and description fields are retrieved.
+      def create_workspace(args: {}, select: DEFAULT_SELECT)
+        query = "mutation { create_workspace(#{Util.format_args(args)}) {#{Util.format_select(select)}}}"
+
+        make_request(query)
+      end
+
+      # Deletes a workspace.
+      #
+      # Requires workspace_id to delete the workspace.
+      # Allows customizing the values to retrieve using the select option.
+      # By default, returns the ID of the workspace deleted.
+      def delete_workspace(workspace_id, select: ["id"])
+        query = "mutation { delete_workspace(workspace_id: #{workspace_id}) {#{Util.format_select(select)}}}"
+
+        make_request(query)
+      end
+    end
+  end
+end

data/lib/monday/resources.rb

@@ -6,6 +6,7 @@ require_relative "resources/board"
 require_relative "resources/board_view"
 require_relative "resources/column"
 require_relative "resources/item"
+require_relative "resources/workspace"
 
 module Monday
   module Resources
@@ -15,5 +16,6 @@ module Monday
     include BoardView
     include Column
     include Item
+    include Workspace
   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,37 @@ 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],
+          "InvalidWorkspaceIdException" => [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.4.0"
 end

data/monday_ruby.gemspec

@@ -8,8 +8,8 @@ repository = "https://github.com/sanifhimani/monday_ruby"
 Gem::Specification.new do |spec|
   spec.name = "monday_ruby"
   spec.version = version
-  spec.authors = ["Sanif Himani"]
-  spec.email = ["sanifhimani92@gmail.com"]
+  spec.authors = ["Sanif Himani", "Wes Hays"]
+  spec.email = ["sanifhimani92@gmail.com", "weshays@gmail.com"]
 
   spec.summary = "Ruby bindings to use the monday.com API"
   spec.description = "A Gem to easily interact with monday.com API using native Ruby"

metadata

@@ -1,18 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: monday_ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Sanif Himani
+- Wes Hays
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-04 00:00:00.000000000 Z
+date: 2023-09-18 00:00:00.000000000 Z
 dependencies: []
 description: A Gem to easily interact with monday.com API using native Ruby
 email:
 - sanifhimani92@gmail.com
+- weshays@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -23,6 +25,7 @@ files:
 - ".vscode/settings.json"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - LICENSE
 - README.md
 - Rakefile
@@ -30,6 +33,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 +70,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
@@ -74,6 +79,7 @@ files:
 - lib/monday/resources/board_view.rb
 - lib/monday/resources/column.rb
 - lib/monday/resources/item.rb
+- lib/monday/resources/workspace.rb
 - lib/monday/response.rb
 - lib/monday/util.rb
 - lib/monday/version.rb
@@ -85,7 +91,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.4.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -102,7 +108,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.14
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Ruby bindings to use the monday.com API