monday_ruby 0.6.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4da1daad80c509a485414efe293d4a628dd6b002871b403c877d150ec12c178
-  data.tar.gz: 10f869bd1cd5fdf8068a8314644bd59ac3da16c98e3794f0a60347fde951f44b
+  metadata.gz: fca12fa6b3f49d85bea9353e7621904cbe773f69fc9b4b18afc641a7c25318a0
+  data.tar.gz: 738fa89ae3732c0bf6afe22c314d7dcc42bae2990bfc313e640ce8aee7183755
 SHA512:
-  metadata.gz: 206f792cdc8f7950c309380a58019dd8ce6874fc2a2dce2da0fdf9cd7cfd5d6e36f1fb8c65715f458de19039e60679bc4b9ba6b9723c3e90a9b8e34aa685011e
-  data.tar.gz: b635c776e2ea724aeb5dad4e047ef03a35226f7ee0031afd3b05831250e0bf4ef64c3835c41df332eb286e1e8992f3206772c0a1c113e9bc8b24825a8f961227
+  metadata.gz: 843ba4a79d3a53b75b8ddfc8eb545d442600fe3b5b90df4f01ced08dd1516c8e9aab4755180b094d7c8fa94a2c330497dbee0b86ecc04071101deb0e236d2d6c
+  data.tar.gz: e6a6b8a7c1b912aee79a55f3da44372cf4d35eed207c7e061f131e6385ed9c48475c87c5722162dbdbf259058eaf13f7acf0e990a765dbc3b33299662120d8ef

data/.env

@@ -1 +1 @@
-token="[REPLACE_TOKEN]"
+token="eyJhbGciOiJIUzI1NiJ9.eyJ0aWQiOjU3ODczMzkyMiwiYWFpIjoxMSwidWlkIjo5NDg5NDgxMywiaWFkIjoiMjAyNS0xMC0yN1QwMToyMToxMy44NDFaIiwicGVyIjoibWU6d3JpdGUiLCJhY3RpZCI6MzIxODc3OTQsInJnbiI6InVzZTEifQ.SgPS-m2FEMHjitKC0SYTYsiQ8vAHZ7ynjDmMwQInneE"

data/.rspec

@@ -1,3 +1,2 @@
---format documentation
 --color
 --require spec_helper

data/.rubocop.yml

@@ -1,6 +1,14 @@
+plugins:
+  - rubocop-rake
+  - rubocop-rspec
+
 AllCops:
   TargetRubyVersion: 2.7
   NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "spec/support/**/*.rb"
+    - "vendor/**/*"
 
 Style/StringLiterals:
   Enabled: true
@@ -20,3 +28,13 @@ Metrics/BlockLength:
 Metrics/MethodLength:
   Exclude:
     - "lib/monday/util.rb"
+
+Metrics/ParameterLists:
+  Exclude:
+    - "lib/monday/resources/group.rb"
+
+RSpec/NestedGroups:
+  Max: 5
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10

data/.simplecov

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
 
+SimpleCov.add_filter "/spec/support/"
 SimpleCov.minimum_coverage 97

data/CHANGELOG.md

@@ -1,3 +1,58 @@
+## v1.1.0 (October 27, 2025)
+
+### Added
+
+- **Cursor-based pagination for items**:
+  - Added `items_page` method to `Board` resource for paginated item retrieval
+  - Added `items_page` method to `Group` resource for paginated group items
+  - Added `items_page` method to `Item` resource for paginated item queries
+  - Support for cursor-based pagination with customizable limits (up to 500 items per page)
+  - Support for filtered queries using `query_params` with rules and operators
+
+- **Deprecation warning system**:
+  - Added `Deprecation` module for issuing deprecation warnings
+  - Marked `delete_subscribers` method for deprecation in v2.0.0
+  - Provides clear migration paths for deprecated methods
+
+- **Configurable request timeouts**:
+  - Added `open_timeout` configuration option (default: 10 seconds)
+  - Added `read_timeout` configuration option (default: 30 seconds)
+  - Configurable at both global and client instance levels
+
+- **Documentation improvements**:
+  - Added CONTRIBUTING.md with development guidelines
+  - Added VCR testing guide in pull request template
+
+### Changed
+
+- Updated Ruby version support matrix in CI (added Ruby 3.3 and 3.4)
+- Updated base64 gem dependency to ~> 0.3.0
+- Improved RuboCop configuration and fixed linting issues
+
+### Fixed
+
+- CI workflow improvements and linting configurations
+
+## v1.0.0 (July 30, 2024)
+
+### Changed
+
+- **Refactor: Flat API replaced by Resource Classes**
+  - The client now uses a modular approach with resource classes instead of a flat API.
+  - Introduced a `Base` class for resources to encapsulate common functionality.
+  - All resource-specific logic is now encapsulated within individual resource classes (e.g., `Account`, `Board`).
+
+### Added
+
+- Support for enums
+
+### Breaking Changes
+
+- **Accessing Resources**:
+  - The way resources are accessed has changed.
+  - **Old**: `client.account`, `client.create_board`
+  - **New**: `client.accounts.query`, `client.board.create`
+
 ## v0.6.2 (April 21, 2024)
 
 ### Bug Fixes

data/CONTRIBUTING.md

@@ -16,6 +16,67 @@ Please follow these steps to have your contribution considered:
 2. Follow the [commit guidelines](#commit-message-guidelines).
 3. After you submit your pull request, verify that all the status checks are passing.
 
+## Testing Guidelines
+
+This project uses [VCR](https://github.com/vcr/vcr) to record HTTP interactions for tests. This means you **do not need a Monday.com API token** to run most tests or contribute to the project.
+
+### Running Tests
+
+To run the test suite:
+
+```bash
+bundle exec rake spec
+```
+
+All tests will use pre-recorded VCR cassettes stored in `spec/fixtures/vcr_cassettes/`.
+
+### Working with VCR Cassettes
+
+**For most contributions, you won't need to modify VCR cassettes.** The existing cassettes cover the current API functionality.
+
+#### When You Need to Record New Cassettes
+
+You only need to record new VCR cassettes when:
+- Adding support for a **new API endpoint** that doesn't have existing test coverage
+- Modifying an existing API call that changes the request/response structure
+
+To record new cassettes:
+
+1. Set your Monday.com API token as an environment variable:
+   ```bash
+   export MONDAY_TOKEN="your_token_here"
+   ```
+
+2. Delete the old cassette file (if updating an existing test):
+   ```bash
+   rm spec/fixtures/vcr_cassettes/your_cassette_name.yml
+   ```
+
+3. Run the specific test to generate a new cassette:
+   ```bash
+   bundle exec rspec spec/path/to/your_spec.rb
+   ```
+
+4. **Important:** Before committing, verify the cassette doesn't contain sensitive data:
+   - VCR automatically filters the `Authorization` header
+   - Check for any other sensitive information in the cassette file
+   - Cassettes are committed to the repository
+
+#### Testing New Features Without API Access
+
+If you're adding a new feature but don't have API access to record cassettes:
+1. Write your implementation and tests
+2. Create a pull request noting that cassettes need to be recorded
+3. A maintainer with API access will record the cassettes for you
+
+### Code Quality
+
+Run RuboCop to ensure code style compliance:
+
+```bash
+bundle exec rake rubocop
+```
+
 ## Commit message guidelines
 
 * Use present tense ("Add feature" not "Added feature")

data/README.md

@@ -4,7 +4,7 @@
 [![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.
+This library provides convenient access to the monday.com API from the application written in Ruby.
 
 The library provides:
 
@@ -12,39 +12,17 @@ The library provides:
 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.**
+**Check out the [Wiki](https://github.com/sanifhimani/monday_ruby/wiki) for detailed documentation on how to use the library.**
 
 ## Installation
 
-You don't need the source code unless you want to modify the gem. If you want to use the package, run:
-
-```sh
+```bash
 gem install monday_ruby
 ```
 
-If you want to build the gem from source:
-
-```sh
-gem build monday_ruby.gemspec
-```
-
-### Requirements
-
-* Ruby 2.7+
-
-### 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"
-```
-
 ## Usage
 
-***Complete list of actions along with examples are provided [here](https://monday-ruby.gitbook.io/docs/).***
+***Complete list of resources along with examples are provided in the [Wiki](https://github.com/sanifhimani/monday_ruby/wiki).***
 
 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).
 
@@ -60,7 +38,6 @@ require "monday_ruby"
 Monday.configure do |config|
   config.token = "<AUTH_TOKEN>"
 end
-
 ```
 
 #### Client specific config
@@ -70,7 +47,7 @@ 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.
+The version configuration field allows you to optionally pass in the version of the API you want to use. By default, the latest stable version is used.
 
 ```ruby
 require "monday_ruby"
@@ -81,6 +58,25 @@ Monday.configure do |config|
 end
 ```
 
+You can also configure request timeouts (new in v1.1.0):
+
+```ruby
+require "monday_ruby"
+
+Monday.configure do |config|
+  config.token = "<AUTH_TOKEN>"
+  config.open_timeout = 10  # seconds (default: 10)
+  config.read_timeout = 30  # seconds (default: 30)
+end
+
+# Or configure per client
+client = Monday::Client.new(
+  token: "<AUTH_TOKEN>",
+  open_timeout: 15,
+  read_timeout: 45
+)
+```
+
 ### Accessing a response object
 
 Get access to response objects by initializing a client and using the appropriate action you want to perform:
@@ -89,35 +85,33 @@ Get access to response objects by initializing a client and using the appropriat
 client = Monday::Client.new(token: "<AUTH_TOKEN>")
 response = client.boards
 
+puts response.success?
 puts response.body
 ```
 
 ### Use cases
 
-Here are some common uses cases for the API client.
+Here are some common use cases for the API client.
 
 #### Fetching all the boards
 
-Initialize the client with the auth token and call the `boards` action.
+Initialize the client with the auth token and call the `boards` method.
 
 ```ruby
 client = Monday::Client.new(token: <AUTH_TOKEN>)
 
-response = client.boards
-# => <Monday::Response ...>
+response = client.boards # => <Monday::Response ...>
 
 # To check if the request was successful
-response.success?
-# => true
+response.success? # => true
 
 # To get the boards from the response
-response.dig("data", "boards")
-# => [...]
+response.body.dig("data", "boards") # => [...]
 ```
 
 #### Creating a new board
 
-Initialize the client with the auth token and call the `create_board` action.
+Initialize the client with the auth token and call the `create_board` method.
 
 ```ruby
 client = Monday::Client.new(token: <AUTH_TOKEN>)
@@ -128,21 +122,19 @@ args = {
   description: "Test board description"
 }
 
-response = client.create_board(args: args)
 # => <Monday::Response ...>
+response = client.create_board(args: args)
 
 # To check if the request was successful
-response.success?
-# => true
+response.success? # => true
 
 # To get the created board from the response
-response.dig("data", "create_board")
-# => { ... }
+response.body.dig("data", "create_board") # => { ... }
 ```
 
 #### Creating a new item on board
 
-Initialize the client with the auth token and call the `create_item` action.
+Initialize the client with the auth token and call the `create_item` method.
 
 ```ruby
 client = Monday::Client.new(token: <AUTH_TOKEN>)
@@ -160,35 +152,89 @@ args = {
   }
 }
 
-response = client.create_item(args: args)
 # => <Monday::Response ...>
+response = client.create_item(args: args)
 
 # To check if the request was successful
-response.success?
-# => true
+response.success? # => true
 
 # To get the created item from the response
-response.dig("data", "create_item")
-# => { ... }
+response.body.dig("data", "create_item") # => { ... }
+```
+
+#### Fetching items with pagination (New in v1.1.0)
+
+The library now supports efficient cursor-based pagination for retrieving large numbers of items. This is the recommended approach for working with boards, groups, or items that contain many records.
+
+```ruby
+client = Monday::Client.new(token: <AUTH_TOKEN>)
+
+# Fetch first page of items from a board (up to 500 items per page)
+response = client.board.items_page(
+  board_ids: <BOARD_ID>,
+  limit: 100
+)
+
+# Extract items and cursor from response
+items = response.body.dig("data", "boards", 0, "items_page", "items")
+cursor = response.body.dig("data", "boards", 0, "items_page", "cursor")
+
+# Fetch next page using cursor
+if cursor
+  next_response = client.board.items_page(
+    board_ids: <BOARD_ID>,
+    limit: 100,
+    cursor: cursor
+  )
+end
+
+# You can also filter items using query_params
+response = client.board.items_page(
+  board_ids: <BOARD_ID>,
+  limit: 50,
+  query_params: {
+    rules: [{ column_id: "status", compare_value: [1] }],
+    operator: :and
+  }
+)
+```
+
+Pagination is also available for groups and items:
+
+```ruby
+# Fetch paginated items from a group
+response = client.group.items_page(
+  board_ids: <BOARD_ID>,
+  group_ids: "group_id",
+  limit: 100
+)
+
+# Fetch paginated items with custom query
+response = client.item.items_page(
+  limit: 100,
+  query_params: {
+    rules: [{ column_id: "status", compare_value: [5] }]
+  }
+)
 ```
 
 ## Development
 
 Run all tests:
 
-```sh
+```bash
 bundle exec rake spec
 ```
 
 Run linter:
 
-```sh
+```bash
 bundle exec rake rubocop
 ```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/sanifhimani/monday_ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/sanifhimani/monday_ruby/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on [GitHub](https://github.com/sanifhimani/monday_ruby). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/sanifhimani/monday_ruby/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 

data/lib/monday/client.rb

@@ -15,20 +15,31 @@ module Monday
   # Client executes requests against the monday.com's API and
   # allows a user to mutate and retrieve resources.
   class Client
-    include Resources
-
     JSON_CONTENT_TYPE = "application/json"
     private_constant :JSON_CONTENT_TYPE
 
     attr_reader :config
 
     def initialize(config_args = {})
-      @config = config_options(config_args)
+      @config = configure(config_args)
+      Resources.initialize(self)
+    end
+
+    def make_request(body)
+      response = Request.post(
+        uri,
+        body,
+        request_headers,
+        open_timeout: @config.open_timeout,
+        read_timeout: @config.read_timeout
+      )
+
+      handle_response(Response.new(response))
     end
 
     private
 
-    def config_options(config_args)
+    def configure(config_args)
       return Monday.config if config_args.empty?
 
       Configuration.new(**config_args)
@@ -45,12 +56,6 @@ module Monday
       }
     end
 
-    def make_request(body)
-      response = Request.post(uri, body, request_headers)
-
-      handle_response(Response.new(response))
-    end
-
     def handle_response(response)
       return response if response.success?
 
@@ -58,13 +63,13 @@ module Monday
     end
 
     def raise_errors(response)
-      raise default_exception(response) unless (200..299).cover?(response.status)
+      raise default_exception(response) unless successful_response?(response.status)
 
       raise response_exception(response)
     end
 
     def response_exception(response)
-      error_code = response.body["error_code"]
+      error_code = response_error_code(response)
 
       return Error.new(response: response) if error_code.nil?
 
@@ -72,8 +77,21 @@ module Monday
       exception_klass.new(message: error_code, response: response, code: code)
     end
 
+    def response_error_code(response)
+      error_code = response.body["error_code"]
+      return error_code unless error_code.nil?
+
+      return unless response.body["errors"].is_a?(Array) && !response.body["errors"].empty?
+
+      response.body.dig("errors", 0, "extensions", "code") || response.body.dig("errors", 0, "extensions", "error_code")
+    end
+
     def default_exception(response)
       Util.status_code_exceptions_mapping(response.status).new(response: response)
     end
+
+    def successful_response?(status)
+      (200..299).cover?(status)
+    end
   end
 end

data/lib/monday/configuration.rb

@@ -11,11 +11,15 @@ module Monday
     DEFAULT_HOST = "https://api.monday.com/v2"
     DEFAULT_TOKEN = nil
     DEFAULT_VERSION = "2023-07"
+    DEFAULT_OPEN_TIMEOUT = 10
+    DEFAULT_READ_TIMEOUT = 30
 
     CONFIGURATION_FIELDS = %i[
       token
       host
       version
+      open_timeout
+      read_timeout
     ].freeze
 
     attr_accessor(*CONFIGURATION_FIELDS)
@@ -27,6 +31,8 @@ module Monday
       @host = DEFAULT_HOST
       @token = DEFAULT_TOKEN
       @version = DEFAULT_VERSION
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @read_timeout = DEFAULT_READ_TIMEOUT
 
       config_args.each do |key, value|
         public_send("#{key}=", value)
@@ -37,6 +43,8 @@ module Monday
       @token = DEFAULT_TOKEN
       @host = DEFAULT_HOST
       @version = DEFAULT_VERSION
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @read_timeout = DEFAULT_READ_TIMEOUT
     end
   end
 end

data/lib/monday/deprecation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Monday
+  # Utility module for handling deprecation warnings
+  module Deprecation
+    # Issues a deprecation warning to stderr
+    #
+    # @param method_name [String] The name of the deprecated method
+    # @param removal_version [String] The version in which the method will be removed
+    # @param alternative [String, nil] The recommended alternative method
+    #
+    # @example
+    #   Deprecation.warn(method_name: "items", removal_version: "2.0.0", alternative: "items_page")
+    #   # => [DEPRECATION] `items` is deprecated and will be removed in v2.0.0. Use `items_page` instead.
+    def self.warn(method_name:, removal_version:, alternative: nil)
+      message = "[DEPRECATION] `#{method_name}` is deprecated and will be removed in v#{removal_version}."
+      message += " Use `#{alternative}` instead." if alternative
+
+      # Output to stderr so it doesn't interfere with normal output
+      Kernel.warn message
+    end
+  end
+end

data/lib/monday/error.rb

@@ -56,13 +56,16 @@ module Monday
   # 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
+  # It is also raised when the body returns the following error_codes:
+  #   UserUnauthorizedException, USER_UNAUTHORIZED
   class AuthorizationError < Error
   end
 
   # RateLimitError is raised when the request returns
   # a 429 status code.
+  #
+  # It is also raised when the body returns the following error_codes:
+  #   ComplexityException, COMPLEXITY_BUDGET_EXHAUSTED
   class RateLimitError < Error
   end
 

data/lib/monday/request.rb

@@ -4,9 +4,12 @@ module Monday
   # Defines the HTTP request methods.
   class Request
     # Performs a POST request
-    def self.post(uri, query, headers)
+    def self.post(uri, query, headers, open_timeout: 10, read_timeout: 30)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = true
+      http.open_timeout = open_timeout
+      http.read_timeout = read_timeout
+
       request = Net::HTTP::Post.new(uri.request_uri, headers)
 
       request.body = {

data/lib/monday/resources/account.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "base"
+
 module Monday
   module Resources
     # Represents Monday.com's account resource.
-    module Account
+    class Account < Base
       DEFAULT_SELECT = %w[id name].freeze
 
       # Retrieves the users account.
       #
       # Allows customizing the values to retrieve using the select option.
       # By default, ID and name are retrieved.
-      def account(select: DEFAULT_SELECT)
-        query = "query { users { account {#{Util.format_select(select)}}}}"
+      def query(select: DEFAULT_SELECT)
+        request_query = "query{users{account {#{Util.format_select(select)}}}}"
 
-        make_request(query)
+        make_request(request_query)
       end
     end
   end

data/lib/monday/resources/activity_log.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "base"
+
 module Monday
   module Resources
     # Represents Monday.com's activity log resource.
-    module ActivityLog
+    class ActivityLog < Base
       DEFAULT_SELECT = %w[id event data].freeze
 
       # Retrieves the activity logs for boards.
@@ -12,11 +14,11 @@ module Monday
       # Allows filtering activity logs using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID, event and data are retrieved.
-      def activity_logs(board_ids, args: {}, select: DEFAULT_SELECT)
-        query = "query { boards(ids: #{board_ids}) " \
-                "{ activity_logs#{Util.format_args(args)} {#{Util.format_select(select)}}}}"
+      def query(board_ids, args: {}, select: DEFAULT_SELECT)
+        request_query = "query{boards(ids: #{board_ids})" \
+                        "{activity_logs#{Util.format_args(args)}{#{Util.format_select(select)}}}}"
 
-        make_request(query)
+        make_request(request_query)
       end
     end
   end