monday_ruby 1.0.0 → 1.2.0

data/lib/monday/client.rb

@@ -2,6 +2,7 @@
 
 require "uri"
 require "net/http"
+require "net/http/post/multipart"
 require "json"
 
 require_relative "configuration"
@@ -26,7 +27,25 @@ 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
+
+    def make_file_request(query, variables)
+      response = Request.post_multipart(
+        files_uri,
+        { query: query, variables: variables },
+        request_multipart_headers,
+        open_timeout: @config.open_timeout,
+        read_timeout: @config.read_timeout
+      )
 
       handle_response(Response.new(response))
     end
@@ -43,6 +62,10 @@ module Monday
       URI(@config.host)
     end
 
+    def files_uri
+      URI(@config.files_host)
+    end
+
     def request_headers
       {
         "Content-Type": "application/json",
@@ -50,6 +73,13 @@ module Monday
       }
     end
 
+    def request_multipart_headers
+      {
+        "Content-Type": "multipart/form-data",
+        Authorization: @config.token
+      }
+    end
+
     def handle_response(response)
       return response if response.success?
 
@@ -63,7 +93,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 +101,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

@@ -7,15 +7,22 @@ module Monday
   #
   # token: used to authenticate the requests
   # host: defaults to https://api.monday.com/v2
+  # files_host: defaults to https://api.monday.com/v2/files
   class Configuration
     DEFAULT_HOST = "https://api.monday.com/v2"
+    DEFAULT_FILES_HOST = "#{DEFAULT_HOST}/file"
     DEFAULT_TOKEN = nil
     DEFAULT_VERSION = "2023-07"
+    DEFAULT_OPEN_TIMEOUT = 10
+    DEFAULT_READ_TIMEOUT = 30
 
     CONFIGURATION_FIELDS = %i[
       token
       host
+      files_host
       version
+      open_timeout
+      read_timeout
     ].freeze
 
     attr_accessor(*CONFIGURATION_FIELDS)
@@ -25,8 +32,11 @@ module Monday
       raise ArgumentError, "Unknown arguments: #{invalid_keys}" unless invalid_keys.empty?
 
       @host = DEFAULT_HOST
+      @files_host = DEFAULT_FILES_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)
@@ -36,7 +46,10 @@ module Monday
     def reset
       @token = DEFAULT_TOKEN
       @host = DEFAULT_HOST
+      @files_host = DEFAULT_FILES_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 = {
@@ -15,5 +18,20 @@ module Monday
 
       http.request(request)
     end
+
+    def self.post_multipart(uri, body, 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
+
+      params = {
+        "query" => body[:query],
+        "variables[file]" => body[:variables][:file]
+      }
+
+      request = Net::HTTP::Post::Multipart.new(uri.request_uri, params, headers)
+      http.request(request)
+    end
   end
 end

data/lib/monday/resources/base.rb

@@ -12,6 +12,10 @@ module Monday
 
       protected
 
+      def make_file_request(query, variables)
+        client.make_file_request(query, variables)
+      end
+
       def make_request(query)
         client.make_request(query)
       end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Monday
+  module Resources
+    # Represents Monday.com's file asset resource.
+    class File < Base
+      DEFAULT_SELECT = %w[id].freeze
+
+      # Adds a file to a file type column for an item.
+      #
+      # Allows customizing the column update using the args option.
+      # Allows customizing the values to retrieve using the select option.
+      # By default, The ID is retrieved.
+      def add_file_to_column(args: {}, select: DEFAULT_SELECT)
+        cloned_args = args.clone
+        variables = { file: cloned_args.delete(:file) }
+        cloned_args.merge!(file: "$file")
+        query = <<~QUERY
+          mutation add_file($file: File!) {
+            add_file_to_column#{Util.format_args(cloned_args)} {#{Util.format_select(select)}}
+          }
+        QUERY
+        make_file_request(query, variables)
+      end
+
+      # Adds a file to an update for an item.
+      #
+      # Allows customizing the update creation using the args option.
+      # Allows customizing the values to retrieve using the select option.
+      # By default, The ID is retrieved.
+      def add_file_to_update(args: {}, select: DEFAULT_SELECT)
+        cloned_args = args.clone
+        variables = { file: cloned_args.delete(:file) }
+        cloned_args.merge!(file: "$file")
+        query = <<~QUERY
+          mutation ($file: File!) {
+            add_file_to_update#{Util.format_args(cloned_args)} {#{Util.format_select(select)}}
+          }
+        QUERY
+        make_file_request(query, variables)
+      end
+
+      # Clear an item's files column. This is a helper method for files
+      # and you could also use the column.change_value to clear the column as well.
+      #
+      # Allows customizing the update creation using the args option.
+      # Allows customizing the values to retrieve using the select option.
+      # By default, ID is retrieved.
+      def clear_file_column(args: {}, select: DEFAULT_SELECT)
+        merged_args = args.merge(value: '{\"clear_all\": true}')
+        query = "mutation { change_column_value#{Util.format_args(merged_args)} {#{Util.format_select(select)}}}"
+        make_request(query)
+      end
+    end
+  end
+end

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,27 @@ 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 if value.to_s.include?("$") # GraphQL query variable
         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.2.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