monday_ruby 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e8164389fc7acb67d40bee3bf79a9768e1256833268e5ef8002c6d9392a5b75
-  data.tar.gz: 29165f3538b8658267944fd2ea91f2bbdf11c916c7967e17cfe55e27397959c3
+  metadata.gz: fca12fa6b3f49d85bea9353e7621904cbe773f69fc9b4b18afc641a7c25318a0
+  data.tar.gz: 738fa89ae3732c0bf6afe22c314d7dcc42bae2990bfc313e640ce8aee7183755
 SHA512:
-  metadata.gz: f21b44ba54e5c14513cd7f39b6709126fe1a5e54a00468da76fc2275230d9a01e7cf4844ae5035bf8777dacd8153ee7571a8a53a3491b6bf4366b47ea324d6ce
-  data.tar.gz: bbaee28c405107767469f7a9386c7d2b991b4e877ccc3b476a360837ca25bb776aee2d05579ef4aa641b74b747cafe2fb73dc72836dd6b8264f61d4982b36729
+  metadata.gz: 843ba4a79d3a53b75b8ddfc8eb545d442600fe3b5b90df4f01ced08dd1516c8e9aab4755180b094d7c8fa94a2c330497dbee0b86ecc04071101deb0e236d2d6c
+  data.tar.gz: e6a6b8a7c1b912aee79a55f3da44372cf4d35eed207c7e061f131e6385ed9c48475c87c5722162dbdbf259058eaf13f7acf0e990a765dbc3b33299662120d8ef

data/.env

@@ -1 +1 @@
-token="eyJhbGciOiJIUzI1NiJ9.eyJ0aWQiOjM4MTE3NTY1MywiYWFpIjoxMSwidWlkIjo2MzEzMDMxMiwiaWFkIjoiMjAyNC0wNy0wN1QxMzo0OTo0Mi4wMzJaIiwicGVyIjoibWU6d3JpdGUiLCJhY3RpZCI6MjQzMDgwODMsInJnbiI6InVzZTEifQ.AKgwPueXJkzm9d0I9y4DzSKBwJ3Vi3t8IsOc2hpyDtk"
+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,38 @@
+## 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

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

@@ -58,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:
@@ -87,7 +106,7 @@ response = client.boards # => <Monday::Response ...>
 response.success? # => true
 
 # To get the boards from the response
-response.dig("data", "boards") # => [...]
+response.body.dig("data", "boards") # => [...]
 ```
 
 #### Creating a new board
@@ -110,7 +129,7 @@ response = client.create_board(args: args)
 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
@@ -140,7 +159,63 @@ response = client.create_item(args: args)
 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

data/lib/monday/client.rb

@@ -26,7 +26,13 @@ module Monday
     end
 
     def make_request(body)
-      response = Request.post(uri, body, request_headers)
+      response = Request.post(
+        uri,
+        body,
+        request_headers,
+        open_timeout: @config.open_timeout,
+        read_timeout: @config.read_timeout
+      )
 
       handle_response(Response.new(response))
     end
@@ -63,7 +69,7 @@ module Monday
     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?
 
@@ -71,6 +77,15 @@ 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

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/board.rb

@@ -7,6 +7,7 @@ module Monday
     # Represents Monday.com's board resource.
     class Board < Base
       DEFAULT_SELECT = %w[id name description].freeze
+      DEFAULT_PAGINATED_SELECT = %w[id name].freeze
 
       # Retrieves all the boards.
       #
@@ -79,11 +80,62 @@ module Monday
       # Allows customizing the values to retrieve using the select option.
       # By default, returns the deleted subscriber IDs.
       def delete_subscribers(board_id, user_ids, select: ["id"])
+        Deprecation.warn(
+          method_name: "delete_subscribers",
+          removal_version: "2.0.0",
+          alternative: "user.delete_from_board"
+        )
+
         query = "mutation{delete_subscribers_from_board(" \
                 "board_id: #{board_id}, user_ids: #{user_ids}){#{Util.format_select(select)}}}"
 
         make_request(query)
       end
+
+      # Retrieves paginated items from a board.
+      #
+      # Uses cursor-based pagination for efficient data retrieval.
+      # The items_page field is the modern replacement for the deprecated items field.
+      #
+      # @param board_id [Integer] The ID of the board
+      # @param limit [Integer] Number of items to retrieve per page (default: 25, max: 500)
+      # @param cursor [String, nil] Pagination cursor for fetching next page (expires after 60 minutes)
+      # @param query_params [Hash, nil] Query parameters for filtering items with rules and operators
+      # @param args [Hash] Additional board query arguments
+      # @param select [Array] Fields to retrieve for each item
+      # @return [Monday::Response] Response containing items and cursor
+      #
+      # @example Fetch first page of items
+      #   response = client.board.items_page(board_id: 123, limit: 50)
+      #   items = response.dig("data", "boards", 0, "items_page", "items")
+      #   cursor = response.dig("data", "boards", 0, "items_page", "cursor")
+      #
+      # @example Fetch next page using cursor
+      #   response = client.board.items_page(board_id: 123, cursor: cursor)
+      #
+      # @example Filter items by column value
+      #   response = client.board.items_page(
+      #     board_id: 123,
+      #     limit: 100,
+      #     query_params: {
+      #       rules: [{ column_id: "status", compare_value: [1] }],
+      #       operator: :and
+      #     }
+      #   )
+      def items_page(board_ids:, limit: 25, cursor: nil, query_params: nil, select: DEFAULT_PAGINATED_SELECT)
+        items_args_parts = ["limit: #{limit}"]
+        items_args_parts << "cursor: \"#{cursor}\"" if cursor
+        items_args_parts << "query_params: #{Util.format_graphql_object(query_params)}" if query_params
+
+        items_args_string = items_args_parts.empty? ? "" : "(#{items_args_parts.join(", ")})"
+
+        items_page_select = "items_page#{items_args_string}{cursor items{#{Util.format_select(select)}}}"
+
+        board_args = { ids: board_ids.is_a?(Array) ? board_ids : [board_ids] }
+        request_query = "query{boards#{Util.format_args(board_args)}{#{items_page_select}}}"
+
+        make_request(request_query)
+      end
     end
   end
 end

data/lib/monday/resources/column.rb

@@ -25,6 +25,12 @@ module Monday
       # Allows customizing the values to retrieve using the select option.
       # By default, ID, title and description fields are retrieved.
       def column_values(board_ids = [], item_ids = [], select: DEFAULT_SELECT)
+        Deprecation.warn(
+          method_name: "column_values",
+          removal_version: "2.0.0",
+          alternative: "item.column_values"
+        )
+
         board_args = board_ids.empty? ? "" : "ids: #{board_ids}"
         item_args = item_ids.empty? ? "" : "ids: #{item_ids}"
         query = "query{boards(#{board_args}){items(#{item_args})" \

data/lib/monday/resources/folder.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Monday
+  module Resources
+    # Represents Monday.com's board resource.
+    class Folder < Base
+      DEFAULT_SELECT = %w[id name].freeze
+
+      # Retrieves all the folders.
+      #
+      # Allows filtering folders using the args option.
+      # Allows customizing the values to retrieve using the select option.
+      # By default, ID and name fields are retrieved.
+      def query(args: {}, select: DEFAULT_SELECT)
+        request_query = "query{folders#{Util.format_args(args)}{#{Util.format_select(select)}}}"
+
+        make_request(request_query)
+      end
+
+      # Create a new folder.
+      #
+      # Allows customizing creating a folder using the args option.
+      # Allows customizing the values to retrieve using the select option.
+      # By default, ID and name fields are retrieved.
+      def create(args: {}, select: DEFAULT_SELECT)
+        query = "mutation{create_folder#{Util.format_args(args)}{#{Util.format_select(select)}}}"
+
+        make_request(query)
+      end
+
+      # Update a folder.
+      #
+      # Allows customizing updating the folder using the args option.
+      # By default, returns the ID of the updated folder.
+      def update(args: {}, select: ["id"])
+        query = "mutation{update_folder#{Util.format_args(args)}{#{Util.format_select(select)}}}"
+
+        make_request(query)
+      end
+
+      # Delete a folder.
+      #
+      # Requires folder_id in args option to delete the folder.
+      # Allows customizing the values to retrieve using the select option.
+      # By default, returns the ID of the folder deleted.
+      def delete(args: {}, select: ["id"])
+        query = "mutation{delete_folder#{Util.format_args(args)}{#{Util.format_select(select)}}}"
+
+        make_request(query)
+      end
+    end
+  end
+end

data/lib/monday/resources/group.rb

@@ -7,6 +7,7 @@ module Monday
     # Represents Monday.com's group resource.
     class Group < Base
       DEFAULT_SELECT = %w[id title].freeze
+      DEFAULT_PAGINATED_SELECT = %w[id name].freeze
 
       # Retrieves all the groups.
       #
@@ -83,6 +84,71 @@ module Monday
 
         make_request(query)
       end
+
+      # Retrieves paginated items from a group.
+      #
+      # Uses cursor-based pagination for efficient data retrieval.
+      # The items_page field is the modern replacement for the deprecated items field.
+      #
+      # @param board_ids [Integer, Array<Integer>] The ID(s) of the board(s) containing the group
+      # @param group_ids [String, Array<String>] The ID(s) of the group(s)
+      # @param limit [Integer] Number of items to retrieve per page (default: 25, max: 500)
+      # @param cursor [String, nil] Pagination cursor for fetching next page (expires after 60 minutes)
+      # @param query_params [Hash, nil] Query parameters for filtering items with rules and operators
+      # @param select [Array] Fields to retrieve for each item
+      # @return [Monday::Response] Response containing items and cursor
+      #
+      # @example Fetch first page of items from a group
+      #   response = client.group.items_page(board_ids: 123, group_ids: "group_1", limit: 50)
+      #   items = response.dig("data", "boards", 0, "groups", 0, "items_page", "items")
+      #   cursor = response.dig("data", "boards", 0, "groups", 0, "items_page", "cursor")
+      #
+      # @example Fetch next page using cursor
+      #   response = client.group.items_page(board_ids: 123, group_ids: "group_1", cursor: cursor)
+      #
+      # @example Filter items by column value
+      #   response = client.group.items_page(
+      #     board_ids: 123,
+      #     group_ids: "group_1",
+      #     limit: 100,
+      #     query_params: {
+      #       rules: [{ column_id: "status", compare_value: [1] }],
+      #       operator: :and
+      #     }
+      #   )
+      def items_page(
+        board_ids:, group_ids:, limit: 25, cursor: nil, query_params: nil, select: DEFAULT_PAGINATED_SELECT
+      )
+        items_page_query = build_items_page_query(limit, cursor, query_params, select)
+        request_query = build_groups_items_page_request(board_ids, group_ids, items_page_query)
+
+        make_request(request_query)
+      end
+
+      private
+
+      def build_items_page_query(limit, cursor, query_params, select)
+        args_parts = ["limit: #{limit}"]
+        args_parts << "cursor: \"#{cursor}\"" if cursor
+        args_parts << "query_params: #{Util.format_graphql_object(query_params)}" if query_params
+
+        args_string = "(#{args_parts.join(", ")})"
+        "items_page#{args_string}{cursor items{#{Util.format_select(select)}}}"
+      end
+
+      def build_groups_items_page_request(board_ids, group_ids, items_page_query)
+        board_args = { ids: board_ids.is_a?(Array) ? board_ids : [board_ids] }
+        group_ids_formatted = format_group_ids(group_ids)
+
+        boards_part = "boards#{Util.format_args(board_args)}"
+        groups_part = "groups(ids: #{group_ids_formatted})"
+        "query{#{boards_part}{#{groups_part}{#{items_page_query}}}}"
+      end
+
+      def format_group_ids(group_ids)
+        ids_array = group_ids.is_a?(Array) ? group_ids : [group_ids]
+        "[#{ids_array.map { |id| "\"#{id}\"" }.join(", ")}]"
+      end
     end
   end
 end

data/lib/monday/resources/item.rb

@@ -7,6 +7,7 @@ module Monday
     # Represents Monday.com's item resource.
     class Item < Base
       DEFAULT_SELECT = %w[id name created_at].freeze
+      DEFAULT_PAGINATED_SELECT = %w[id name].freeze
 
       # Retrieves all the items for the boards.
       #
@@ -63,6 +64,67 @@ module Monday
 
         make_request(query)
       end
+
+      # Retrieves paginated items filtered by column values.
+      #
+      # Enables searching for items based on specific column values.
+      # Uses cursor-based pagination for efficient data retrieval.
+      #
+      # @param board_id [Integer] The ID of the board
+      # @param columns [Array<Hash>, nil] Column filtering criteria (mutually exclusive with cursor)
+      #   Each hash should contain :column_id and :column_values
+      # @param limit [Integer] Number of items to retrieve per page (default: 25, max: 500)
+      # @param cursor [String, nil] Pagination cursor for fetching next page (mutually exclusive with columns)
+      # @param select [Array] Fields to retrieve for each item
+      # @return [Monday::Response] Response containing items and cursor
+      #
+      # @example Search items by column values
+      #   response = client.item.page_by_column_values(
+      #     board_id: 123,
+      #     columns: [
+      #       { column_id: "status", column_values: ["Done", "Working on it"] },
+      #       { column_id: "text", column_values: ["High Priority"] }
+      #     ],
+      #     limit: 50
+      #   )
+      #   items = response.dig("data", "items_page_by_column_values", "items")
+      #   cursor = response.dig("data", "items_page_by_column_values", "cursor")
+      #
+      # @example Fetch next page using cursor
+      #   response = client.item.page_by_column_values(
+      #     board_id: 123,
+      #     cursor: cursor
+      #   )
+      #
+      # @note Supported column types: Checkbox, Country, Date, Dropdown, Email, Hour, Link,
+      #   Long Text, Numbers, People, Phone, Status, Text, Timeline, World Clock
+      # @note Columns use AND logic; values within a column use ANY_OF logic
+      def page_by_column_values(board_id:, columns: nil, limit: 25, cursor: nil, select: DEFAULT_PAGINATED_SELECT)
+        query_string = build_items_page_by_column_values_query(board_id, columns, limit, cursor, select)
+        make_request(query_string)
+      end
+
+      private
+
+      def build_items_page_by_column_values_query(board_id, columns, limit, cursor, select)
+        args_parts = ["board_id: #{board_id}", "limit: #{limit}"]
+        args_parts << "cursor: \"#{cursor}\"" if cursor
+        args_parts << "columns: #{format_columns(columns)}" if columns
+
+        args_string = "(#{args_parts.join(", ")})"
+        "query{items_page_by_column_values#{args_string}{cursor items{#{Util.format_select(select)}}}}"
+      end
+
+      def format_columns(columns)
+        return nil unless columns
+
+        column_strings = columns.map do |col|
+          values = col[:column_values].map { |v| "\"#{v}\"" }.join(", ")
+          "{column_id: \"#{col[:column_id]}\", column_values: [#{values}]}"
+        end
+
+        "[#{column_strings.join(", ")}]"
+      end
     end
   end
 end

data/lib/monday/util.rb

@@ -29,6 +29,18 @@ module Monday
         values
       end
 
+      # Formats a hash as a GraphQL input object (not JSON string)
+      # Used for complex input types like ItemsQuery
+      #
+      # input: { rules: [{ column_id: "status", compare_value: [1] }], operator: :and }
+      # output: { rules: [{ column_id: "status", compare_value: [1] }], operator: and }
+      def format_graphql_object(hash)
+        formatted = hash.map do |key, value|
+          "#{key}: #{format_graphql_value(value)}"
+        end.join(", ")
+        "{#{formatted}}"
+      end
+
       def status_code_exceptions_mapping(status_code)
         {
           "500" => InternalServerError,
@@ -43,7 +55,9 @@ module Monday
       def response_error_exceptions_mapping(error_code)
         {
           "ComplexityException" => [ComplexityError, 429],
+          "COMPLEXITY_BUDGET_EXHAUSTED" => [RateLimitError, 429],
           "UserUnauthorizedException" => [AuthorizationError, 403],
+          "USER_UNAUTHORIZED" => [AuthorizationError, 403],
           "ResourceNotFoundException" => [ResourceNotFoundError, 404],
           "InvalidUserIdException" => [InvalidRequestError, 400],
           "InvalidVersionException" => [InvalidRequestError, 400],
@@ -58,7 +72,8 @@ module Monday
           "ItemNameTooLongException" => [InvalidRequestError, 400],
           "ColumnValueException" => [InvalidRequestError, 400],
           "CorrectedValueException" => [InvalidRequestError, 400],
-          "InvalidWorkspaceIdException" => [InvalidRequestError, 400]
+          "InvalidWorkspaceIdException" => [InvalidRequestError, 400],
+          "INTERNAL_SERVER_ERROR" => [InternalServerError, 500]
         }[error_code] || [Error, 400]
       end
 
@@ -76,10 +91,26 @@ module Monday
         end.join(" ")
       end
 
+      def format_graphql_value(value)
+        case value
+        when Hash
+          format_graphql_object(value)
+        when Array
+          "[#{value.map { |v| format_graphql_value(v) }.join(", ")}]"
+        when Integer, TrueClass, FalseClass
+          value
+        when String
+          "\"#{value}\""
+        else
+          value.to_s
+        end
+      end
+
       def formatted_args_value(value)
         return value if value.is_a?(Symbol)
         return value.to_json.to_json if value.is_a?(Hash)
         return value if integer?(value)
+        return "[#{value.map { |v| formatted_args_value(v) }.join(", ")}]" if value.is_a?(Array)
 
         "\"#{value}\""
       end

data/lib/monday/version.rb

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

data/lib/monday_ruby.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "monday/client"
+require_relative "monday/deprecation"
 require_relative "monday/version"
 
 # Module to configure the library globally

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monday_ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Sanif Himani
 - Wes Hays
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-30 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -17,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
 description: A Gem to easily interact with monday.com API using native Ruby
 email:
 - sanifhimani92@gmail.com
@@ -46,6 +45,7 @@ files:
 - Rakefile
 - lib/monday/client.rb
 - lib/monday/configuration.rb
+- lib/monday/deprecation.rb
 - lib/monday/error.rb
 - lib/monday/request.rb
 - lib/monday/resources.rb
@@ -55,6 +55,7 @@ files:
 - lib/monday/resources/board.rb
 - lib/monday/resources/board_view.rb
 - lib/monday/resources/column.rb
+- lib/monday/resources/folder.rb
 - lib/monday/resources/group.rb
 - lib/monday/resources/item.rb
 - lib/monday/resources/subitem.rb
@@ -64,16 +65,14 @@ files:
 - lib/monday/util.rb
 - lib/monday/version.rb
 - lib/monday_ruby.rb
-- monday_ruby.gemspec
 homepage: https://github.com/sanifhimani/monday_ruby
 licenses:
 - MIT
 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/v1.0.0/CHANGELOG.md
+  changelog_uri: https://github.com/sanifhimani/monday_ruby/blob/v1.1.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -88,8 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby bindings to use the monday.com API
 test_files: []

data/monday_ruby.gemspec

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/monday/version"
-
-version = Monday::VERSION
-repository = "https://github.com/sanifhimani/monday_ruby"
-
-Gem::Specification.new do |spec|
-  spec.name = "monday_ruby"
-  spec.version = version
-  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"
-  spec.homepage = repository
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.7.0"
-
-  spec.metadata = {
-    "homepage_uri" => spec.homepage,
-    "documentation_uri" => "https://monday-ruby.gitbook.io/docs/",
-    "changelog_uri" => "#{repository}/blob/v#{version}/CHANGELOG.md",
-    "rubygems_mfa_required" => "true"
-  }
-
-  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 Gemfile])
-    end
-  end
-
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  spec.add_dependency "base64", "~> 0.2.0"
-end