auction_fun_core 0.8.5 → 0.8.9

data/i18n/pt-BR/mail/auction_context/pre_auction/auction_start_reminder.pt-BR.yml

@@ -0,0 +1,11 @@
+pt-BR:
+  mail:
+    auction_context:
+      pre_auction:
+        auction_start_reminder_mailer:
+          subject: "O leilão %{title} começará em breve!"
+          body:
+            description: "Estamos entusiasmados em informar que o leilão em que você está participando começará em breve!"
+            auction_date: "Hora de Início"
+            link_to_auction: "Clique no link abaixo para ver os detalhes do leilão"
+            thanks: "Agradecemos pela sua participação e desejamos boa sorte!"

data/i18n/pt-BR/mail/user_context/registration.pt-BR.yml

@@ -1,9 +1,5 @@
 pt-BR:
   mail:
-    general:
-      hello: "Olá %{name}"
-      app_name: "AuctionFun"
-      team: "Time AuctionFun"
     user_context:
       registration:
         subject: "Bem vindo a AuctionFun"

data/lib/auction_fun_core/business/configuration.rb

@@ -2,16 +2,47 @@
 
 module AuctionFunCore
   module Business
+    # The Configuration module contains constants that configure various aspects of auctions,
+    # user settings, and other business rules within the AuctionFun application.
     module Configuration
+      # An array of available auction kinds derived from auction relations.
+      # @return [Array<String>] a list of all possible auction kinds
       AUCTION_KINDS = Relations::Auctions::KINDS.values
+
+      # An array of valid auction statuses derived from auction relations.
+      # @return [Array<String>] a list of all valid auction statuses
       AUCTION_STATUSES = Relations::Auctions::STATUSES.values
+
+      # The minimum length for an auction title.
+      # @return [Integer] the minimum number of characters allowed in an auction title
       AUCTION_MIN_TITLE_LENGTH = 6
+
+      # The maximum length for an auction title.
+      # @return [Integer] the maximum number of characters allowed in an auction title
       AUCTION_MAX_TITLE_LENGTH = 255
+
+      # The minimum value for the auction stopwatch timer.
+      # @return [Integer] the minimum seconds count for the auction stopwatch timer
       AUCTION_STOPWATCH_MIN_VALUE = 15
+
+      # The maximum value for the auction stopwatch timer.
+      # @return [Integer] the maximum seconds count for the auction stopwatch timer
       AUCTION_STOPWATCH_MAX_VALUE = 60
+
+      # The minimum length for a user's name.
+      # @return [Integer] the minimum number of characters allowed in a person's name
       MIN_NAME_LENGTH = 6
+
+      # The maximum length for a user's name.
+      # @return [Integer] the maximum number of characters allowed in a person's name
       MAX_NAME_LENGTH = 128
+
+      # The minimum length for a user's password.
+      # @return [Integer] the minimum number of characters required in a person's password
       MIN_PASSWORD_LENGTH = 6
+
+      # The maximum length for a user's password.
+      # @return [Integer] the maximum number of characters allowed in a person's password
       MAX_PASSWORD_LENGTH = 128
     end
   end

data/lib/auction_fun_core/business/token_generator.rb

@@ -2,13 +2,31 @@
 
 module AuctionFunCore
   module Business
-    # Responsible for generating interaction tokens with system users for general operations.
+    # The TokenGenerator module is responsible for generating interaction tokens
+    # used in various parts of the AuctionFun application for authentication and
+    # verification purposes, particularly in interactions with system users.
     module TokenGenerator
+      # Generates a secure, URL-safe base64 token primarily used for email verification.
+      # This method modifies certain characters to avoid common readability issues.
+      #
+      # @param length [Integer] the desired length of the generated token before modification
+      # @return [String] a URL-safe, base64 encoded string suitable for email verification links
+      # @example Generating an email token
+      #   email_token = AuctionFunCore::Business::TokenGenerator.generate_email_token(20)
+      #   puts email_token  # Output example: "V4Ph2wkJG_bRzs_zuGyJ"
       def self.generate_email_token(length = 20)
         rlength = (length * 3) / 4
         SecureRandom.urlsafe_base64(rlength).tr("lIO0", "sxyz")
       end
 
+      # Generates a numerical token used for phone verification processes.
+      # The token is zero-padded to ensure it meets the required length.
+      #
+      # @param length [Integer] the desired length of the numerical token
+      # @return [String] a string of digits, zero-padded to the specified length
+      # @example Generating a phone token
+      #   phone_token = AuctionFunCore::Business::TokenGenerator.generate_phone_token(6)
+      #   puts phone_token  # Output example: "045673"
       def self.generate_phone_token(length = 6)
         rand(0o00000..999_999).to_s.rjust(length, "0")
       end

data/lib/auction_fun_core/contracts/application_contract.rb

@@ -4,7 +4,10 @@ require "phonelib"
 
 module AuctionFunCore
   module Contracts
-    # Abstract base class for contracts.
+    ##
+    # The class includes several macros for common validation tasks, such as validating email format,
+    # login format, name format, phone number format, and password format. These macros utilize
+    # regular expressions and predefined length ranges to ensure the input data meets specific criteria.
     # @abstract
     class ApplicationContract < Dry::Validation::Contract
       include AuctionFunCore::Business::Configuration
@@ -17,18 +20,21 @@ module AuctionFunCore
       config.messages.top_namespace = "contracts"
       config.messages.load_paths << Application.root.join("i18n/#{I18n.default_locale}/contracts/contracts.#{I18n.default_locale}.yml").to_s
 
+      # Validates whether the provided value matches the standard email format.
       register_macro(:email_format) do
         next if EMAIL_REGEX.match?(value)
 
         key.failure(I18n.t(:email_format, scope: I18N_MACRO_SCOPE))
       end
 
+      # Validates whether the provided value matches either the email format or a valid phone number format using Phonelib.
       register_macro(:login_format) do
         next if EMAIL_REGEX.match?(value) || Phonelib.parse(value).valid?
 
         key.failure(I18n.t(:login_format, scope: I18N_MACRO_SCOPE))
       end
 
+      # Validates whether the length of the provided name falls within the specified range.
       register_macro(:name_format) do
         next if value.length.between?(MIN_NAME_LENGTH, MAX_NAME_LENGTH)
 
@@ -37,12 +43,14 @@ module AuctionFunCore
         )
       end
 
+      # Validates whether the provided value matches a valid phone number format using Phonelib.
       register_macro(:phone_format) do
         next if ::Phonelib.parse(value).valid?
 
         key.failure(I18n.t(:phone_format, scope: I18N_MACRO_SCOPE))
       end
 
+      # Validates whether the length of the provided password falls within the specified range.
       register_macro(:password_format) do
         next if value.length.between?(MIN_PASSWORD_LENGTH, MAX_PASSWORD_LENGTH)
 

data/lib/auction_fun_core/contracts/auction_context/create_contract.rb

@@ -3,15 +3,36 @@
 module AuctionFunCore
   module Contracts
     module AuctionContext
-      # Contract class to create new auctions.
+      # This class is designed to validate the creation of new auctions.
+      # It includes various validations such as staff existence, auction kind, timing, and initial bids.
+      #
+      # @example Creating a new auction
+      #   contract = AuctionFunCore::Contracts::AuctionContext::CreateContract.new
+      #   attributes = {
+      #     staff_id: 1,
+      #     title: "Rare Antique Vase",
+      #     kind: "standard",
+      #     started_at: Time.current + 5.days,
+      #     finished_at: Time.current + 10.days,
+      #     initial_bid_cents: 5000
+      #   }
+      #   result = contract.call(attributes)
+      #   if result.success?
+      #     puts "Auction created successfully."
+      #   else
+      #     puts "Failed to create auction: #{result.errors.to_h}"
+      #   end
+      #
       class CreateContract < Contracts::ApplicationContract
         include AuctionFunCore::Business::Configuration
 
+        # Additional validations specific for non-penny auctions.
         REQUIRED_FINISHED_AT = AUCTION_KINDS - ["penny"]
 
+        # Repository initialized to retrieve staff data for validation.
         option :staff_repo, default: proc { Repos::StaffContext::StaffRepository.new }
 
-        # @param [Hash] opts Sets an allowed list of parameters, as well as some initial validations.
+        # Defines necessary parameters and initializes some default values.
         params do
           required(:staff_id).filled(:integer)
           required(:title).filled(:string, size?: (AUCTION_MIN_TITLE_LENGTH..AUCTION_MAX_TITLE_LENGTH))
@@ -22,7 +43,7 @@ module AuctionFunCore
           optional(:initial_bid_cents).filled(:integer)
           optional(:stopwatch).filled(:integer)
 
-          # Keys with a blank value are discarded.
+          # Parameters specifying the required input types and fields.
           before(:value_coercer) do |result|
             result.to_h.compact
           end
@@ -33,59 +54,53 @@ module AuctionFunCore
           end
         end
 
-        # Validation for staff.
-        # Validate whether the given staff is valid at the database level.
+        # Validates the existence of the staff.
         rule(:staff_id) do |context:|
           context[:staff] ||= staff_repo.by_id(value)
           key.failure(I18n.t("contracts.errors.custom.default.not_found")) unless context[:staff]
         end
 
-        # Validation for started_at.
-        # Validates if the entered date is greater than or equal to the current time.
+        # Validates that the starting time of the auction is in the future.
         rule(:started_at) do
           key.failure(I18n.t("contracts.errors.custom.default.future")) if key? && value <= Time.current
         end
 
-        # Specific validation when the auction type is informed and it is not penny,
-        # it must be mandatory to inform the auction closing date/time
+        # Validates that the finished_at time is specified for auctions types that require it,
+        # and is not specified for "penny" auctions.
         rule(:finished_at, :kind) do
           if key?(:kind) && !key?(:finished_at) && REQUIRED_FINISHED_AT.include?(values[:kind])
             key.failure(I18n.t("contracts.errors.filled?"))
           end
         end
 
-        # Basic specific validation to check if the auction end time
-        # is less than or equal to the start time.
+        # Validates that the auction end time is later than the start time.
         rule(:finished_at, :started_at) do
           if key?(:finished_at) && (values[:finished_at] <= values[:started_at])
             key.failure(I18n.t("contracts.errors.custom.auction_context.create.finished_at"))
           end
         end
 
-        # Validation for initial bid amount.
-        #
+        # Validates the initial bid amount based on auction type.
         rule(:initial_bid_cents) do
-          # Must be filled if auction kind is not type penny.
+          # Must be specified and positive for non-penny auction types.
           key.failure(I18n.t("contracts.errors.filled?")) if !key? && REQUIRED_FINISHED_AT.include?(values[:kind])
 
-          # Must be greater than zero if action kind is not type penny.
           if key? && REQUIRED_FINISHED_AT.include?(values[:kind]) && values[:initial_bid_cents] <= 0
             key.failure(I18n.t("contracts.errors.gt?", num: 0))
           end
 
-          # Must be equal to zero if auction kind is type penny.
+          # Must be zero for penny auctions to ensure fairness.
           if key? && values[:kind] == "penny" && !values[:initial_bid_cents].zero?
             key.failure(I18n.t("contracts.errors.eql?", left: 0))
           end
         end
 
-        # Validation for stopwatch.
-        #
+        # Validates stopwatch settings for penny auctions.
         rule(:stopwatch) do
-          # Must be filled if auction kind is type penny.
+          # Stopwatch must be specified for penny auctions.
           key.failure(I18n.t("contracts.errors.filled?")) if !key? && values[:kind] == "penny"
 
-          # Must be an integer between 15 and 60.
+          # Stopwatch value must fall within the specified range.
           if key? && values[:kind] == "penny" && !value.between?(AUCTION_STOPWATCH_MIN_VALUE, AUCTION_STOPWATCH_MAX_VALUE)
             key.failure(
               I18n.t(

data/lib/auction_fun_core/contracts/auction_context/post_auction/participant_contract.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module AuctionFunCore
+  module Contracts
+    module AuctionContext
+      module PostAuction
+        ##
+        # This class is used to validate the participation of users in an auction.
+        # This contract ensures that both the auction and the participant exist and that the participant
+        # has already at least placed a bid. It utilizes repositories to fetch data about auctions, users, and bids.
+        #
+        # @example Using this class to validate a participant
+        #   contract = AuctionFunCore::Contracts::AuctionContext::PostAuction::ParticipantContract.new
+        #   attributes = { auction_id: 1, participant_id: 102 }
+        #   validation_result = contract.call(attributes)
+        #   if validation_result.success?
+        #     puts "Participant validation passed"
+        #   else
+        #     puts "Participant validation failed: #{validation_result.errors.to_h}"
+        #   end
+        #
+        class ParticipantContract < Contracts::ApplicationContract
+          # Scope for internationalization (i18n) entries specific to errors in this contract.
+          I18N_SCOPE = "contracts.errors.custom.auction_context.post_auction.participation"
+
+          # Repository options initialized by default. These repositories handle data retrieval.
+          option :auction_repository, default: proc { Repos::AuctionContext::AuctionRepository.new }
+          option :user_repository, default: proc { Repos::UserContext::UserRepository.new }
+          option :bid_repository, default: proc { Repos::BidContext::BidRepository.new }
+
+          # Defines the data types and required fields for the contract.
+          params do
+            required(:auction_id).filled(:integer)
+            required(:participant_id).filled(:integer)
+          end
+
+          # Validation rule for auction_id to ensure the auction exists.
+          # @param context [Hash] Optional context hash to store data and state during validation.
+          rule(:auction_id) do |context:|
+            context[:auction] ||= auction_repository.by_id(value)
+            key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:auction]
+          end
+
+          # Validation rule for participant_id to ensure the participant exists.
+          # @param context [Hash] Optional context hash to store data and state during validation.
+          rule(:participant_id) do |context:|
+            context[:participant] ||= user_repository.by_id(value)
+            key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:participant]
+          end
+
+          # Combined validation rule for auction_id and participant_id to check that the participant
+          # has not already placed a bid in the auction.
+          # @param context [Hash] Context containing the auction and participant objects.
+          rule(:auction_id, :participant_id) do |context:|
+            next if (rule_error?(:auction_id) || schema_error?(:auction_id)) || (rule_error?(:winner_id) || schema_error?(:winner_id))
+            next if bid_repository.exists?(auction_id: values[:auction_id], user_id: values[:participant_id])
+
+            key(:participant_id).failure(I18n.t("none", scope: I18N_SCOPE))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auction_fun_core/contracts/auction_context/post_auction/winner_contract.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module AuctionFunCore
+  module Contracts
+    module AuctionContext
+      module PostAuction
+        ##
+        # This class validates the identification of the winning bidder
+        # in an auction context. It ensures that both the auction and the winner exist
+        # and are correctly associated within the system.
+        #
+        # @example Using this class to validate a winner
+        #   contract = AuctionFunCore::Contracts::AuctionContext::PostAuction::WinnerContract.new
+        #   attributes = { auction_id: 1, winner_id: 102 }
+        #   validation_result = contract.call(attributes)
+        #   if validation_result.success?
+        #     puts "Winner validation passed"
+        #   else
+        #     puts "Winner validation failed: #{validation_result.errors.to_h}"
+        #   end
+        #
+        class WinnerContract < Contracts::ApplicationContract
+          # Internationalization (i18n) scope for error messages related to winner validation.
+          I18N_SCOPE = "contracts.errors.custom.auction_context.post_auction.winner"
+
+          # Repositories initialized by default to handle data retrieval for validation.
+          option :auction_repository, default: proc { Repos::AuctionContext::AuctionRepository.new }
+          option :user_repository, default: proc { Repos::UserContext::UserRepository.new }
+
+          # Parameters defining the expected input types and required fields.
+          params do
+            required(:auction_id).filled(:integer)
+            required(:winner_id).filled(:integer)
+          end
+
+          # Validation rule to ensure the auction exists.
+          # @param context [Hash] Optional context hash to store data and state during validation.
+          rule(:auction_id) do |context:|
+            context[:auction] ||= auction_repository.by_id(value)
+            key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:auction]
+          end
+
+          # Validation rule to ensure the winner exists.
+          # @param context [Hash] Optional context hash to store data and state during validation.
+          rule(:winner_id) do |context:|
+            context[:winner] ||= user_repository.by_id(value)
+            key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:winner]
+          end
+
+          # Combined rule to ensure that the declared winner is the actual winner recorded in the auction.
+          # @param context [Hash] Context containing the auction and winner objects.
+          rule(:auction_id, :winner_id) do |context:|
+            next if (rule_error?(:auction_id) || schema_error?(:auction_id)) || (rule_error?(:winner_id) || schema_error?(:winner_id))
+            next if context[:auction].winner_id == values[:winner_id]
+
+            key(:winner_id).failure(I18n.t("wrong", scope: I18N_SCOPE))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auction_fun_core/contracts/auction_context/pre_auction/auction_start_reminder_contract.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module AuctionFunCore
+  module Contracts
+    module AuctionContext
+      module PreAuction
+        # The AuctionStartReminderContract class validates the scheduled reminder for the auction start.
+        # It checks if the auction associated with the provided auction ID has not started yet and validates accordingly.
+        #
+        # @example Validating auction reminder
+        #   contract = AuctionFunCore::Contracts::AuctionContext::PreAuction::AuctionStartReminderContract.new
+        #   attributes = { auction_id: 123 }
+        #   result = contract.call(attributes)
+        #   if result.success?
+        #     puts "Reminder setup is valid."
+        #   else
+        #     puts "Failed to validate reminder: #{result.errors.to_h}"
+        #   end
+        #
+        class AuctionStartReminderContract < Contracts::ApplicationContract
+          # Scope for internationalization (i18n) entries specific to errors in this contract.
+          I18N_SCOPE = "contracts.errors.custom.auction_context.pre_auction.auction_start_reminder"
+
+          # Default repository initialization to retrieve auction data.
+          option :auction_repository, default: proc { Repos::AuctionContext::AuctionRepository.new }
+
+          # Defines the necessary parameters and their types.
+          params do
+            required(:auction_id).filled(:integer)
+          end
+
+          # Validation rule to ensure the referenced auction exists.
+          rule(:auction_id) do |context:|
+            context[:auction] ||= auction_repository.by_id(value)
+            key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:auction]
+          end
+
+          # Additional validation to confirm the auction has not started yet.
+          rule do |context:|
+            next if context[:auction].present? && context[:auction].not_started?
+
+            key(:base).failure(I18n.t("auction_already_started", scope: I18N_SCOPE))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auction_fun_core/contracts/auction_context/processor/finish/closed_contract.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module AuctionFunCore
+  module Contracts
+    module AuctionContext
+      module Processor
+        module Finish
+          ##
+          # This class is designed for validate the finishing closed auctions. It ensures that
+          # the auction to be closed exists, is of the correct kind ('closed'), and is in the correct
+          # status ('running') to be finalized.
+          #
+          # @example Validating a closed auction
+          #   contract = AuctionFunCore::Contracts::AuctionContext::Processor::Finish::ClosedContract.new
+          #   attributes = { auction_id: 123 }
+          #   result = contract.call(attributes)
+          #   if result.success?
+          #     puts "Auction can be finished."
+          #   else
+          #     puts "Failed to finish auction: #{result.errors.to_h}"
+          #   end
+          #
+          class ClosedContract < Contracts::ApplicationContract
+            # Internationalization (i18n) scope for error messages.
+            I18N_SCOPE = "contracts.errors.custom.auction_context.processor.finish"
+
+            # Repository initialized to retrieve auction data for validation.
+            option :auction_repository, default: proc { Repos::AuctionContext::AuctionRepository.new }
+
+            # Parameters specifying the required input types and fields.
+            params do
+              required(:auction_id).filled(:integer)
+            end
+
+            # Validates the existence of the auction.
+            rule(:auction_id) do |context:|
+              context[:auction] ||= auction_repository.by_id(value)
+              key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:auction]
+            end
+
+            # Validates the kind of the auction to ensure it is 'closed'.
+            rule do |context:|
+              next if context[:auction].present? && context[:auction].kind == "closed"
+
+              key(:base).failure(I18n.t("invalid_kind", scope: I18N_SCOPE))
+            end
+
+            # Validates the status of the auction to ensure it is 'running'.
+            rule do |context:|
+              next if context[:auction].present? && context[:auction].status == "running"
+
+              key(:base).failure(I18n.t("invalid_status", scope: I18N_SCOPE))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auction_fun_core/contracts/auction_context/processor/finish/penny_contract.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module AuctionFunCore
+  module Contracts
+    module AuctionContext
+      module Processor
+        module Finish
+          ##
+          # This class is designed for validate the finishing penny auctions. It ensures that
+          # the auction to be penny exists, is of the correct kind ('penny'), and is in the correct
+          # status ('running') to be finalized.
+          #
+          # @example Validating a penny auction
+          #   contract = AuctionFunCore::Contracts::AuctionContext::Processor::Finish::PennyContract.new
+          #   attributes = { auction_id: 123 }
+          #   result = contract.call(attributes)
+          #   if result.success?
+          #     puts "Auction can be finished."
+          #   else
+          #     puts "Failed to finish auction: #{result.errors.to_h}"
+          #   end
+          #
+          class PennyContract < Contracts::ApplicationContract
+            # Internationalization (i18n) scope for error messages.
+            I18N_SCOPE = "contracts.errors.custom.auction_context.processor.finish"
+
+            # Repository initialized to retrieve auction data for validation.
+            option :auction_repository, default: proc { Repos::AuctionContext::AuctionRepository.new }
+
+            # Parameters specifying the required input types and fields.
+            params do
+              required(:auction_id).filled(:integer)
+            end
+
+            # Validates the existence of the auction.
+            rule(:auction_id) do |context:|
+              context[:auction] ||= auction_repository.by_id(value)
+
+              key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:auction]
+            end
+
+            # Validates the kind of the auction to ensure it is 'penny'.
+            rule do |context:|
+              next if context[:auction].present? && context[:auction].kind == "penny"
+
+              key(:base).failure(I18n.t("invalid_kind", scope: I18N_SCOPE))
+            end
+
+            # Validates the status of the auction to ensure it is 'running'.
+            rule do |context:|
+              next if context[:auction].present? && context[:auction].status == "running"
+
+              key(:base).failure(I18n.t("invalid_status", scope: I18N_SCOPE))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auction_fun_core/contracts/auction_context/processor/finish/standard_contract.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module AuctionFunCore
+  module Contracts
+    module AuctionContext
+      module Processor
+        module Finish
+          ##
+          # This class is designed for validate the finishing standard auctions. It ensures that
+          # the auction to be standard exists, is of the correct kind ('standard'), and is in the correct
+          # status ('running') to be finalized.
+          #
+          # @example Validating a standard auction
+          #   contract = AuctionFunCore::Contracts::AuctionContext::Processor::Finish::StandardContract.new
+          #   attributes = { auction_id: 123 }
+          #   result = contract.call(attributes)
+          #   if result.success?
+          #     puts "Auction can be finished."
+          #   else
+          #     puts "Failed to finish auction: #{result.errors.to_h}"
+          #   end
+          #
+          class StandardContract < Contracts::ApplicationContract
+            # Internationalization (i18n) scope for error messages.
+            I18N_SCOPE = "contracts.errors.custom.auction_context.processor.finish"
+
+            # Repository initialized to retrieve auction data for validation.
+            option :auction_repository, default: proc { Repos::AuctionContext::AuctionRepository.new }
+
+            # Parameters specifying the required input types and fields.
+            params do
+              required(:auction_id).filled(:integer)
+            end
+
+            # Validates the existence of the auction.
+            rule(:auction_id) do |context:|
+              context[:auction] ||= auction_repository.by_id(value)
+
+              key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:auction]
+            end
+
+            # Validates the kind of the auction to ensure it is 'standard'.
+            rule do |context:|
+              next if context[:auction].present? && context[:auction].kind == "standard"
+
+              key(:base).failure(I18n.t("invalid_kind", scope: I18N_SCOPE))
+            end
+
+            # Validates the status of the auction to ensure it is 'running'.
+            rule do |context:|
+              next if context[:auction].present? && context[:auction].status == "running"
+
+              key(:base).failure(I18n.t("invalid_status", scope: I18N_SCOPE))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auction_fun_core/contracts/auction_context/processor/pause_contract.rb

@@ -5,18 +5,30 @@ module AuctionFunCore
     module AuctionContext
       module Processor
         ##
-        # Contract class for pause auction.
+        # This class is designed to validate pausing an auction. It ensures
+        # that the auction exists in the database and checks that only auctions with
+        # a "running" status can be paused.
+        #
+        # @example Pausing an auction
+        #   contract = AuctionFunCore::Contracts::AuctionContext::Processor::PauseContract.new
+        #   attributes = { auction_id: 123 }
+        #   result = contract.call(attributes)
+        #   if result.success?
+        #     puts "Auction paused successfully."
+        #   else
+        #     puts "Failed to pause auction: #{result.errors.to_h}"
+        #   end
         #
         class PauseContract < Contracts::ApplicationContract
+          # Repository initialized to retrieve auction data for validation.
           option :auction_repository, default: proc { Repos::AuctionContext::AuctionRepository.new }
 
+          # Parameters specifying the required input types and fields.
           params do
             required(:auction_id).filled(:integer)
           end
 
-          # Validation for auction.
-          # Validates if the auction exists in the database and check if  only auctions
-          # with a "running" status can be paused.
+          # Validates the existence of the auction and its status.
           rule(:auction_id) do |context:|
             context[:auction] ||= auction_repository.by_id(value)
             key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:auction]