monday_ruby 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd002aba608dc2f94d8203eee88629ff3185e305e09096ac6206e650b2b6f54f
-  data.tar.gz: b2abc595ac065fad70b823917f063cd8ffd1088c736b38ba18c5417272d6a8ae
+  metadata.gz: b952365eaf332b933932dea993d33470bc585c9eadcf0dc7525e4550794313d2
+  data.tar.gz: 665a9d53d8a06972f88022040a28bf8003fa13247aa0bdac60e21f7ca8be9da5
 SHA512:
-  metadata.gz: ab592952c05ad6fcf5c7cc2ae78039939daa46f0f7bac2cc8460e66566d6da05a123c0a9bc23cbae993cd1df6122be275528d12bf87c114bc46bb88fc094e554
-  data.tar.gz: 198556d5abce107ec8109f4b32eee408b618ccea654dbe45f3b0016b71f1be0a9440114aba607a6fdb49009c14f8b49607fd161dbeb246e70dea0f5237a34744
+  metadata.gz: 2af82867a8586bb1bdd6f665f6e584b9e41ea76d0a74fab00f56d408d4357fee4986fde25df96403f0ba8284a4ecc99c61e97e1a4e9668e6024ca7e94574a22e
+  data.tar.gz: 7b66ffafb1c9bfd6bb5c24de9c19438acf89ba59a0a07204ca76a38e18bd043e183077ccda3042453560f71f18c307c73bf8b6f1d161e75a42a39bcadb468229

data/.env

@@ -0,0 +1 @@
+token="[REPLACE_TOKEN]"

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 2.7
   NewCops: enable
 
 Style/StringLiterals:
@@ -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,22 @@
+## 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
+
+- Support for global config
+- VCR for test suite
+
+### Removed
+
+- [BREAKING] Support for Ruby 2.6
+
 ## v0.1.0 (June 28, 2023)
 
 - Initial release

data/README.md

@@ -1,8 +1,16 @@
 # Monday API Library for Ruby
 
 ![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. It includes a pre-defined set of actions for the API resources.
+This library provides convenient access to the monday.com API from the application written in the Ruby language.
+
+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.**
 
@@ -22,7 +30,7 @@ gem build monday_ruby.gemspec
 
 ### Requirements
 
-* Ruby 2.6+
+* Ruby 2.7+
 
 ### Bundler
 
@@ -40,12 +48,39 @@ gem "monday_ruby"
 
 The library needs to be configured with your account's authentication token which is available on the Admin tab on monday.com. Elaborate documentation can be found [here](https://developer.monday.com/api-reference/docs/authentication).
 
+### Configuration
+
+Once you have the authentication token, you can either globally configure the library or you can configure a specific client.
+
+#### Global config
+
+```ruby
+require "monday_ruby"
+
+Monday.configure do |config|
+  config.token = "<AUTH_TOKEN>"
+end
+
+```
+
+#### Client specific config
 ```ruby
 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

@@ -0,0 +1,13 @@
+# Monday API Library for Ruby
+
+This library provides convenient access to the monday.com API from the application written in the Ruby language.
+
+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
+
+* Ruby 2.7+

data/docs/SUMMARY.md

@@ -0,0 +1,40 @@
+# Table of contents
+
+* [Monday API Library for Ruby](README.md)
+* [Getting Started](getting-started.md)
+* [Configuration](configuration.md)
+* [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)
+  * [Activity Log](resources/activity-log/README.md)
+    * [#activity\_logs](resources/activity-log/activity\_logs.md)
+  * [Board View](resources/board-view/README.md)
+    * [#board\_views](resources/board-view/board\_views.md)
+  * [Board](resources/board/README.md)
+    * [#boards](resources/board/boards.md)
+    * [#create\_board](resources/board/create\_board.md)
+    * [#duplicate\_board](resources/board/duplicate\_board.md)
+    * [#update\_board](resources/board/update\_board.md)
+    * [#archive\_board](resources/board/archive\_board.md)
+    * [#delete\_board](resources/board/delete\_board.md)
+    * [#delete\_board\_subscribers](resources/board/delete\_board\_subscribers.md)
+  * [Column](resources/column/README.md)
+    * [#columns](resources/column/columns.md)
+    * [#column\_values](resources/column/column\_values.md)
+    * [#create\_column](resources/column/create\_column.md)
+    * [#change\_column\_title](resources/column/change\_column\_title.md)
+    * [#change\_column\_metadata](resources/column/change\_column\_metadata.md)
+    * [#change\_column\_value](resources/column/change\_column\_value.md)
+    * [#change\_simple\_column\_value](resources/column/change\_simple\_column\_value.md)
+    * [#change\_multiple\_column\_value](resources/column/change\_multiple\_column\_value.md)
+    * [#delete\_column](resources/column/delete\_column.md)
+  * [Item](resources/item/README.md)
+    * [#items](resources/item/items.md)
+    * [#create\_item](resources/item/create\_item.md)
+    * [#duplicate\_item](resources/item/duplicate\_item.md)
+    * [#archive\_item](resources/item/archive\_item.md)
+    * [#delete\_item](resources/item/delete\_item.md)

data/docs/client.md

@@ -0,0 +1,15 @@
+# Client
+
+The Monday client is flat, meaning most API actions are available as methods on the client object. To initialize a client, run the following:
+
+{% code lineNumbers="true" %}
+```ruby
+# If the library is configured globally
+client_with_global_config = Monday::Client.new
+
+# For a specific client
+client = Monday::Client.new(token: <AUTH_TOKEN>)
+```
+{% endcode %}
+
+You can then use all the [resources](resources/) using the client object.

data/docs/configuration.md

@@ -0,0 +1,40 @@
+# Configuration
+
+To interact with the API, you must provide a valid auth token. This token can be generated from the Administration tab on the account. For more authentication information, please look at monday.com's [API documentation](https://developer.monday.com/api-reference/docs/authentication).
+
+Once you have the authentication token, you can either globally configure the library or you can configure a specific client.
+
+### Global
+
+To configure the library globally, you can do the following:
+
+```ruby
+require "monday_ruby"
+
+Monday.configure do |config|
+  config.token = <AUTH_TOKEN>
+end
+```
+
+### Client specific config
+
+To configure a client, you can do the following:
+
+```ruby
+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/docs/getting-started.md

@@ -0,0 +1,25 @@
+# Getting Started
+
+### Installation
+
+You don't need the source code unless you want to modify the gem. If you want to use the package, run the following:
+
+```sh
+gem install monday_ruby
+```
+
+If you want to build the gem from the source:
+
+```sh
+gem build monday_ruby.gemspec
+```
+
+### Bundler
+
+If you are installing via bundler, you should be sure to use the HTTPS rubygems source in your Gemfile, as any gems fetched over HTTP could potentially be compromised in transit and alter the code of gems fetched securely over HTTPS:
+
+```ruby
+source "https://rubygems.org"
+
+gem "monday_ruby"
+```

data/docs/quick-start.md

@@ -0,0 +1,269 @@
+# Quick Start
+
+The following is the minimum needed to fetch all the boards with their IDs and column IDs:
+
+{% code lineNumbers="true" %}
+```ruby
+require "monday_ruby"
+
+client = Monday::Client.new(token: <AUTH_TOKEN>)
+
+select = [
+  "id",
+  {
+    columns: "id"
+  }
+]
+
+response = client.boards(select: select)
+# => <Monday::Response ...>
+
+puts response.body
+```
+{% endcode %}
+
+The response body from the above query would be as follows:
+
+{% code lineNumbers="true" %}
+```json
+{
+  "data": {
+    "boards": [
+      {
+        "id": "123",
+        "columns": [
+          {
+            "id": "name"
+          },
+          {
+            "id": "subitems"
+          },
+          {
+            "id": "work_status"
+          },
+          {
+            "id": "keywords"
+          }
+        ]
+      },
+      {
+        "id": "456",
+        "columns": [
+          {
+            "id": "name"
+          },
+          {
+            "id": "person"
+          },
+          {
+            "id": "status"
+          },
+          {
+            "id": "date0"
+          }
+        ]
+      },
+    ]
+  },
+  "account_id": 123
+}
+```
+{% endcode %}
+
+### Advanced select query
+
+The following is the minimum needed to fetch:
+
+1. All the boards' IDs, names and count of items on each board.
+2. The ID, title and type for the columns on each board.
+3. The ID, name and the value of the items on each board.
+
+{% code lineNumbers="true" %}
+```ruby
+require "monday_ruby"
+
+client = Monday::Client.new(token: <AUTH_TOKEN>)
+
+select = [
+  "id",
+  "name",
+  "items_count",
+  {
+    columns: %w[id title type],
+    items: [
+      "id",
+      "name",
+      {
+        column_values: "value"
+      }
+    ]
+  }
+]
+
+response = client.boards(select: select)
+# => <Monday::Response ...>
+
+puts response.body
+```
+{% endcode %}
+
+The response body from the above query would be as follows:
+
+{% code lineNumbers="true" %}
+```json
+{
+  "data": {
+    "boards": [
+      {
+        "id": "123",
+        "name": "New test board",
+        "items_count": 2,
+        "columns": [
+          {
+            "id": "name",
+            "title": "Name",
+            "type": "name"
+          },
+          {
+            "id": "subitems",
+            "title": "Subitems",
+            "type": "subtasks"
+          },
+          {
+            "id": "work_status",
+            "title": "Status",
+            "type": "color"
+          },
+          {
+            "id": "keywords",
+            "title": "Keywords",
+            "type": "dropdown"
+          }
+        ],
+        "items": [
+          {
+            "id": "4708726090",
+            "name": "Task 1",
+            "column_values": [
+              {
+                "value": null
+              },
+              {
+                "value": "{\"index\":0,\"changed_at\":\"2023-06-27T16:21:22.192Z\"}"
+              },
+              {
+                "value": "{\"ids\":[1]}"
+              }
+            ]
+          },
+          {
+            "id": "4713421325",
+            "name": "New item",
+            "column_values": [
+              {
+                "value": null
+              },
+              {
+                "value": null
+              },
+              {
+                "value": null
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "id": "456",
+        "name": "Your first board",
+        "items_count": 3,
+        "columns": [
+          {
+            "id": "name",
+            "title": "Name",
+            "type": "name"
+          },
+          {
+            "id": "subitems",
+            "title": "Subitems",
+            "type": "subtasks"
+          },
+          {
+            "id": "person",
+            "title": "Person",
+            "type": "multiple-person"
+          },
+          {
+            "id": "status",
+            "title": "Status",
+            "type": "color"
+          },
+          {
+            "id": "date4",
+            "title": "Date",
+            "type": "date"
+          }
+        ],
+        "items": [
+          {
+            "id": "4691485763",
+            "name": "Item 1",
+            "column_values": [
+              {
+                "value": null
+              },
+              {
+                "value": "{\"changed_at\":\"2022-10-26T12:39:58.664Z\",\"personsAndTeams\":[{\"id\":44865791,\"kind\":\"person\"}]}"
+              },
+              {
+                "value": "{\"index\":0,\"post_id\":null,\"changed_at\":\"2019-03-01T17:24:57.321Z\"}"
+              },
+              {
+                "value": "{\"date\":\"2023-06-21\",\"icon\":null,\"changed_at\":\"2022-12-18T14:03:06.455Z\"}"
+              }
+            ]
+          },
+          {
+            "id": "4691485774",
+            "name": "Item 2",
+            "column_values": [
+              {
+                "value": null
+              },
+              {
+                "value": null
+              },
+              {
+                "value": "{\"index\":1,\"post_id\":null,\"changed_at\":\"2019-03-01T17:28:23.178Z\"}"
+              },
+              {
+                "value": "{\"date\":\"2023-06-23\",\"icon\":null,\"changed_at\":\"2022-12-25T12:31:18.096Z\"}"
+              }
+            ]
+          },
+          {
+            "id": "4691485784",
+            "name": "Item 3",
+            "column_values": [
+              {
+                "value": null
+              },
+              {
+                "value": null
+              },
+              {
+                "value": "{\"index\":2,\"post_id\":null,\"changed_at\":\"2022-12-11T14:33:50.083Z\"}"
+              },
+              {
+                "value": "{\"date\":\"2023-06-25\",\"changed_at\":\"2022-12-25T12:31:20.220Z\"}"
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "account_id": 123
+}
+```
+{% endcode %}

data/docs/resources/README.md

@@ -0,0 +1,27 @@
+# Resources
+
+Once you have the client set up, you can call the API resources using the client.
+
+{% content-ref url="account/" %}
+[account](account/)
+{% endcontent-ref %}
+
+{% content-ref url="activity-log/" %}
+[activity-log](activity-log/)
+{% endcontent-ref %}
+
+{% content-ref url="board-view/" %}
+[board-view](board-view/)
+{% endcontent-ref %}
+
+{% content-ref url="board/" %}
+[board](board/)
+{% endcontent-ref %}
+
+{% content-ref url="column/" %}
+[column](column/)
+{% endcontent-ref %}
+
+{% content-ref url="item/" %}
+[item](item/)
+{% endcontent-ref %}

data/docs/resources/account/README.md

@@ -0,0 +1,9 @@
+# Account
+
+The account API is used to access the account data. It includes the following methods:
+
+[accounts.md](accounts.md "mention")
+
+{% hint style="info" %}
+Visit monday.com's API documentation to know more about the [account API](https://developer.monday.com/api-reference/docs/account).
+{% endhint %}