monday_ruby 0.6.2 → 1.1.0

data/lib/monday/resources/base.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Monday
+  module Resources
+    # Base class for all resources.
+    class Base
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      protected
+
+      def make_request(query)
+        client.make_request(query)
+      end
+    end
+  end
+end

data/lib/monday/resources/board.rb

@@ -1,20 +1,23 @@
 # frozen_string_literal: true
 
+require_relative "base"
+
 module Monday
   module Resources
     # Represents Monday.com's board resource.
-    module Board
+    class Board < Base
       DEFAULT_SELECT = %w[id name description].freeze
+      DEFAULT_PAGINATED_SELECT = %w[id name].freeze
 
       # Retrieves all the boards.
       #
       # Allows filtering boards using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID, name and description fields are retrieved.
-      def boards(args: {}, select: DEFAULT_SELECT)
-        query = "query { boards#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def query(args: {}, select: DEFAULT_SELECT)
+        request_query = "query{boards#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
-        make_request(query)
+        make_request(request_query)
       end
 
       # Creates a new boards.
@@ -22,8 +25,8 @@ module Monday
       # Allows customizing creating a board 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_board(args: {}, select: DEFAULT_SELECT)
-        query = "mutation { create_board#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def create(args: {}, select: DEFAULT_SELECT)
+        query = "mutation{create_board#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -33,8 +36,8 @@ module Monday
       # Allows customizing duplicating the board using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID, name and description fields are retrieved.
-      def duplicate_board(args: {}, select: DEFAULT_SELECT)
-        query = "mutation { duplicate_board#{Util.format_args(args)} { board {#{Util.format_select(select)}}}}"
+      def duplicate(args: {}, select: DEFAULT_SELECT)
+        query = "mutation{duplicate_board#{Util.format_args(args)}{board{#{Util.format_select(select)}}}}"
 
         make_request(query)
       end
@@ -43,8 +46,8 @@ module Monday
       #
       # Allows customizing updating the board using the args option.
       # Returns the ID of the updated board.
-      def update_board(args: {})
-        query = "mutation { update_board#{Util.format_args(args)}}"
+      def update(args: {})
+        query = "mutation{update_board#{Util.format_args(args)}}"
 
         make_request(query)
       end
@@ -54,8 +57,8 @@ module Monday
       # Requires board_id to archive board.
       # Allows customizing the values to retrieve using the select option.
       # By default, returns the ID of the board archived.
-      def archive_board(board_id, select: ["id"])
-        query = "mutation { archive_board(board_id: #{board_id}) {#{Util.format_select(select)}}}"
+      def archive(board_id, select: ["id"])
+        query = "mutation{archive_board(board_id: #{board_id}){#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -65,8 +68,8 @@ module Monday
       # Requires board_id to delete the board.
       # Allows customizing the values to retrieve using the select option.
       # By default, returns the ID of the board deleted.
-      def delete_board(board_id, select: ["id"])
-        query = "mutation { delete_board(board_id: #{board_id}) {#{Util.format_select(select)}}}"
+      def delete(board_id, select: ["id"])
+        query = "mutation{delete_board(board_id: #{board_id}){#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -76,12 +79,63 @@ module Monday
       # Requires board_id and user_ids to delete subscribers.
       # Allows customizing the values to retrieve using the select option.
       # By default, returns the deleted subscriber IDs.
-      def delete_board_subscribers(board_id, user_ids, select: ["id"])
-        query = "mutation { delete_subscribers_from_board(" \
-                "board_id: #{board_id}, user_ids: #{user_ids}) {#{Util.format_select(select)}}}"
+      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/board_view.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "base"
+
 module Monday
   module Resources
     # Represents Monday.com's board view resource.
-    module BoardView
+    class BoardView < Base
       DEFAULT_SELECT = %w[id name type].freeze
 
       # Retrieves board views from a specific board.
@@ -11,10 +13,10 @@ module Monday
       # Allows filtering views using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID, name and type fields are retrieved.
-      def board_views(args: {}, select: DEFAULT_SELECT)
-        query = "query { boards#{Util.format_args(args)} { views {#{Util.format_select(select)}}}}"
+      def query(args: {}, select: DEFAULT_SELECT)
+        request_query = "query{boards#{Util.format_args(args)}{views{#{Util.format_select(select)}}}}"
 
-        make_request(query)
+        make_request(request_query)
       end
     end
   end

data/lib/monday/resources/column.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "base"
+
 module Monday
   module Resources
     # Represents Monday.com's column resource.
-    module Column
+    class Column < Base
       DEFAULT_SELECT = %w[id title description].freeze
 
       # Retrieves all the columns for the boards.
@@ -11,10 +13,10 @@ module Monday
       # Allows filtering columns using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID, title and description fields are retrieved.
-      def columns(args: {}, select: DEFAULT_SELECT)
-        query = "query { boards#{Util.format_args(args)} { columns {#{Util.format_select(select)}}}}"
+      def query(args: {}, select: DEFAULT_SELECT)
+        request_query = "query{boards#{Util.format_args(args)}{columns{#{Util.format_select(select)}}}}"
 
-        make_request(query)
+        make_request(request_query)
       end
 
       # Retrieves metadata about one or a collection of columns.
@@ -23,10 +25,16 @@ 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}) " \
-                "{ column_values {#{Util.format_select(select)}}}}}"
+        query = "query{boards(#{board_args}){items(#{item_args})" \
+                "{column_values{#{Util.format_select(select)}}}}}"
 
         make_request(query)
       end
@@ -36,8 +44,8 @@ module Monday
       # Allows customizing the column creation using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID, title and description fields are retrieved.
-      def create_column(args: {}, select: DEFAULT_SELECT)
-        query = "mutation { create_column#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def create(args: {}, select: DEFAULT_SELECT)
+        query = "mutation{create_column#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -47,8 +55,8 @@ module Monday
       # Allows customizing the update using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID, title and description fields are retrieved.
-      def change_column_title(args: {}, select: DEFAULT_SELECT)
-        query = "mutation { change_column_title#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def change_title(args: {}, select: DEFAULT_SELECT)
+        query = "mutation{change_column_title#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -58,8 +66,8 @@ module Monday
       # Allows customizing the update using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID, title and description fields are retrieved.
-      def change_column_metadata(args: {}, select: DEFAULT_SELECT)
-        query = "mutation { change_column_metadata#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def change_metadata(args: {}, select: DEFAULT_SELECT)
+        query = "mutation{change_column_metadata#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -69,8 +77,8 @@ module Monday
       # Allows customizing the update using the args option.
       # Allows customizing the item values to retrieve using the select option.
       # By default, ID, and name fields are retrieved.
-      def change_column_value(args: {}, select: %w[id name])
-        query = "mutation { change_column_value#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def change_value(args: {}, select: %w[id name])
+        query = "mutation{change_column_value#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -80,8 +88,8 @@ module Monday
       # Allows customizing the update using the args option.
       # Allows customizing the item values to retrieve using the select option.
       # By default, ID, and name fields are retrieved.
-      def change_simple_column_value(args: {}, select: %w[id name])
-        query = "mutation { change_simple_column_value#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def change_simple_value(args: {}, select: %w[id name])
+        query = "mutation{change_simple_column_value#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -91,8 +99,8 @@ module Monday
       # Allows customizing the update using the args option.
       # Allows customizing the item values to retrieve using the select option.
       # By default, ID, and name fields are retrieved.
-      def change_multiple_column_value(args: {}, select: %w[id name])
-        query = "mutation { change_multiple_column_values#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def change_multiple_values(args: {}, select: %w[id name])
+        query = "mutation{change_multiple_column_values#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -102,8 +110,8 @@ module Monday
       # Requires board_id and column_id to delete.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID is retrieved.
-      def delete_column(board_id, column_id, select: %w[id])
-        query = "mutation { delete_column(board_id: #{board_id}, column_id: #{column_id}) " \
+      def delete(board_id, column_id, select: %w[id])
+        query = "mutation{delete_column(board_id: #{board_id}, column_id: \"#{column_id}\")" \
                 "{#{Util.format_select(select)}}}"
 
         make_request(query)

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

@@ -1,20 +1,23 @@
 # frozen_string_literal: true
 
+require_relative "base"
+
 module Monday
   module Resources
     # Represents Monday.com's group resource.
-    module Group
+    class Group < Base
       DEFAULT_SELECT = %w[id title].freeze
+      DEFAULT_PAGINATED_SELECT = %w[id name].freeze
 
       # Retrieves all the groups.
       #
       # Allows filtering groups using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID and title fields are retrieved.
-      def groups(args: {}, select: DEFAULT_SELECT)
-        query = "query { boards#{Util.format_args(args)} { groups{#{Util.format_select(select)}}}}"
+      def query(args: {}, select: DEFAULT_SELECT)
+        request_query = "query{boards#{Util.format_args(args)}{groups{#{Util.format_select(select)}}}}"
 
-        make_request(query)
+        make_request(request_query)
       end
 
       # Creates a new group.
@@ -22,8 +25,8 @@ module Monday
       # Allows customizing creating a group using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID and title fields are retrieved.
-      def create_group(args: {}, select: DEFAULT_SELECT)
-        query = "mutation { create_group#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def create(args: {}, select: DEFAULT_SELECT)
+        query = "mutation{create_group#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -32,8 +35,8 @@ module Monday
       #
       # Allows customizing updating the group using the args option.
       # By default, returns the ID of the updated group.
-      def update_group(args: {}, select: ["id"])
-        query = "mutation { update_group#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def update(args: {}, select: ["id"])
+        query = "mutation{update_group#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -43,8 +46,8 @@ module Monday
       # Requires board_id and group_id in args option to delete the group.
       # Allows customizing the values to retrieve using the select option.
       # By default, returns the ID of the group deleted.
-      def delete_group(args: {}, select: ["id"])
-        query = "mutation { delete_group#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def delete(args: {}, select: ["id"])
+        query = "mutation{delete_group#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -54,8 +57,8 @@ module Monday
       # Requires board_id and group_id in args option to archive the group.
       # Allows customizing the values to retrieve using the select option.
       # By default, returns the ID of the group archived.
-      def archive_group(args: {}, select: ["id"])
-        query = "mutation { archive_group#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def archive(args: {}, select: ["id"])
+        query = "mutation{archive_group#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -65,8 +68,8 @@ module Monday
       # Requires board_id and group_id in args option to duplicate the group.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID and title fields are retrieved.
-      def duplicate_group(args: {}, select: DEFAULT_SELECT)
-        query = "mutation { duplicate_group#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def duplicate(args: {}, select: DEFAULT_SELECT)
+        query = "mutation{duplicate_group#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -76,11 +79,76 @@ module Monday
       # Requires item_id and group_id in args option to move an item to a group.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID and title fields are retrieved.
-      def move_item_to_group(args: {}, select: ["id"])
-        query = "mutation { move_item_to_group#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def move_item(args: {}, select: ["id"])
+        query = "mutation{move_item_to_group#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         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

@@ -1,20 +1,23 @@
 # frozen_string_literal: true
 
+require_relative "base"
+
 module Monday
   module Resources
     # Represents Monday.com's item resource.
-    module Item
+    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.
       #
       # Allows filtering items using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID, name and created_at fields are retrieved.
-      def items(args: {}, select: DEFAULT_SELECT)
-        query = "query { items#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def query(args: {}, select: DEFAULT_SELECT)
+        request_query = "query{items#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
-        make_request(query)
+        make_request(request_query)
       end
 
       # Creates a new item.
@@ -22,8 +25,8 @@ module Monday
       # Allows customizing the item creation using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID, name and created_at fields are retrieved.
-      def create_item(args: {}, select: DEFAULT_SELECT)
-        query = "mutation { create_item#{Util.format_args(args)} {#{Util.format_select(select)}}}"
+      def create(args: {}, select: DEFAULT_SELECT)
+        query = "mutation{create_item#{Util.format_args(args)}{#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -33,9 +36,9 @@ module Monday
       # Allows customizing the item creation using the args option.
       # Allows customizing the values to retrieve using the select option.
       # By default, ID, name and created_at fields are retrieved.
-      def duplicate_item(board_id, item_id, with_updates, select: DEFAULT_SELECT)
-        query = "mutation { duplicate_item(board_id: #{board_id}, item_id: #{item_id}, " \
-                "with_updates: #{with_updates}) {#{Util.format_select(select)}}}"
+      def duplicate(board_id, item_id, with_updates, select: DEFAULT_SELECT)
+        query = "mutation{duplicate_item(board_id: #{board_id}, item_id: #{item_id}, " \
+                "with_updates: #{with_updates}){#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -45,8 +48,8 @@ module Monday
       # Requires item_id to archive item.
       # Allows customizing the values to retrieve using the select option.
       # By default, returns the ID of the archived item.
-      def archive_item(item_id, select: %w[id])
-        query = "mutation { archive_item(item_id: #{item_id}) {#{Util.format_select(select)}}}"
+      def archive(item_id, select: %w[id])
+        query = "mutation{archive_item(item_id: #{item_id}){#{Util.format_select(select)}}}"
 
         make_request(query)
       end
@@ -56,11 +59,72 @@ module Monday
       # Requires item_id to delete item.
       # Allows customizing the values to retrieve using the select option.
       # By default, returns the ID of the deleted item.
-      def delete_item(item_id, select: %w[id])
-        query = "mutation { delete_item(item_id: #{item_id}) {#{Util.format_select(select)}}}"
+      def delete(item_id, select: %w[id])
+        query = "mutation{delete_item(item_id: #{item_id}){#{Util.format_select(select)}}}"
 
         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