auction_fun_core 0.8.5 → 0.8.9

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

@@ -5,28 +5,40 @@ module AuctionFunCore
     module AuctionContext
       module Processor
         ##
-        # Contract class for start auctions.
+        # This class is designed to validate the initiation of auctions. It ensures
+        # the auction exists and is of a valid kind, and also manages specific rules for auctions
+        # that require a stopwatch, such as penny auctions.
+        #
+        # @example Starting an auction
+        #   contract = AuctionFunCore::Contracts::AuctionContext::Processor::StartContract.new
+        #   attributes = { auction_id: 123, kind: "penny", stopwatch: 30 }
+        #   result = contract.call(attributes)
+        #   if result.success?
+        #     puts "Auction started successfully."
+        #   else
+        #     puts "Failed to start auction: #{result.errors.to_h}"
+        #   end
         #
         class StartContract < Contracts::ApplicationContract
           include AuctionFunCore::Business::Configuration
 
+          # Repository initialized to retrieve auction data for validation.
           option :auction_repo, default: proc { Repos::AuctionContext::AuctionRepository.new }
 
+          # Parameters specifying the required input types and fields.
           params do
             required(:auction_id).filled(:integer)
             required(:kind).value(included_in?: AUCTION_KINDS)
             optional(:stopwatch).filled(:integer)
           end
 
-          # Validation for auction.
-          # Validates if the auction exists in the database.
+          # Validates the existence of the auction.
           rule(:auction_id) do |context:|
             context[:auction] ||= auction_repo.by_id(value)
             key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:auction]
           end
 
-          # Validation for stopwatch.
-          #
+          # Validates the requirements for the stopwatch in penny auctions.
           rule(:stopwatch) do
             # Must be filled if auction kind is type penny.
             key.failure(I18n.t("contracts.errors.filled?")) if !key? && values[:kind] == "penny"

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

@@ -5,18 +5,30 @@ module AuctionFunCore
     module AuctionContext
       module Processor
         ##
-        # Contract class for unpause auction.
+        # This class is designed to validate the resumption of auctions.
+        # It ensures that the auction exists in the database and checks that the auction
+        # is currently in a "paused" status, allowing it to be unpaused.
+        #
+        # @example Unpausing an auction
+        #   contract = AuctionFunCore::Contracts::AuctionContext::Processor::UnpauseContract.new
+        #   attributes = { auction_id: 123 }
+        #   result = contract.call(attributes)
+        #   if result.success?
+        #     puts "Auction resumed successfully."
+        #   else
+        #     puts "Failed to resume auction: #{result.errors.to_h}"
+        #   end
         #
         class UnpauseContract < 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 and checks if the
-          # auction has a paused status.
+          # Validates the existence of the auction and checks 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]

data/lib/auction_fun_core/contracts/bid_context/create_bid_closed_contract.rb

@@ -3,13 +3,27 @@
 module AuctionFunCore
   module Contracts
     module BidContext
-      # Contract class to create new bids.
+      # This class validates the creation of new bids for closed-type auctions.
+      # It ensures the bid is placed by a valid user on a valid auction that is open for bids, and that
+      # the bid value meets or exceeds the starting bid required by the auction.
+      # Furthermore, only one bid per participant is allowed.
+      #
+      # @example Creating a bid for a closed auction
+      #   contract = AuctionFunCore::Contracts::BidContext::CreateBidClosedContract.new
+      #   attributes = { auction_id: 123, user_id: 2, value_cents: 10000 }
+      #   result = contract.call(attributes)
+      #   if result.success?
+      #     puts "Bid created successfully."
+      #   else
+      #     puts "Failed to create bid: #{result.errors.to_h}"
+      #   end
       class CreateBidClosedContract < Contracts::ApplicationContract
+        # Repositories initialized to retrieve data for validation.
         option :user_repository, default: proc { Repos::UserContext::UserRepository.new }
         option :auction_repository, default: proc { Repos::AuctionContext::AuctionRepository.new }
         option :bid_repository, default: proc { Repos::BidContext::BidRepository.new }
 
-        # @param [Hash] opts Sets an allowed list of parameters, as well as some initial validations.
+        # Parameters specifying the required input types and fields.
         params do
           required(:auction_id).filled(:integer)
           required(:user_id).filled(:integer)
@@ -21,9 +35,7 @@ module AuctionFunCore
           end
         end
 
-        # Validation for auction.
-        # validate whether the given auction is valid at the database level.
-        # validate if the auction is open to receive bids
+        # Validates the auction's validity and status for receiving bids.
         rule(:auction_id) do |context:|
           context[:auction] ||= auction_repository.by_id(value)
 
@@ -42,9 +54,7 @@ module AuctionFunCore
           end
         end
 
-        # Validation for user.
-        # Validate whether the given user is valid at the database level.
-        # Validates if user has already placed a bid
+        # Validates the user's existence and checks if they have already placed a bid.
         rule(:user_id) do |context:|
           context[:user] ||= user_repository.by_id(value)
 
@@ -57,8 +67,7 @@ module AuctionFunCore
           end
         end
 
-        # Validation for value bid.
-        # The bid amount must be greater than or equal to the starting bid.
+        # Validates that the bid amount is greater than or equal to the auction's starting bid.
         rule(:value_cents) do |context:|
           unless rule_error?(:user_id)
             closed_auction_bid_value_is_gteq_initial_bid?(key, value, context[:auction].initial_bid_cents)
@@ -67,7 +76,7 @@ module AuctionFunCore
 
         private
 
-        # Checks if bid amount must be greater than or equal to the starting bid.
+        # Helper method to check if the bid amount meets the minimum required bid.
         def closed_auction_bid_value_is_gteq_initial_bid?(key, value_cents, minimal_bid_cents)
           return unless value_cents < minimal_bid_cents
 

data/lib/auction_fun_core/contracts/bid_context/create_bid_penny_contract.rb

@@ -3,12 +3,25 @@
 module AuctionFunCore
   module Contracts
     module BidContext
-      # Contract class to create new bids.
+      # This class validates the creation of new bids for penny-type auctions.
+      # It guarantees that the bid can only be made within the correct status of this type of auction,
+      # in addition, the participant must have sufficient balance in their wallet to place a new bid.
+      #
+      # @example Creating a bid for a penny auction
+      #   contract = AuctionFunCore::Contracts::BidContext::CreateBidPennyContract.new
+      #   attributes = { auction_id: 123, user_id: 2 }
+      #   result = contract.call(attributes)
+      #   if result.success?
+      #     puts "Bid created successfully."
+      #   else
+      #     puts "Failed to create bid: #{result.errors.to_h}"
+      #   end
       class CreateBidPennyContract < Contracts::ApplicationContract
+        # Repositories initialized to retrieve data for validation.
         option :user_repo, default: proc { Repos::UserContext::UserRepository.new }
         option :auction_repo, default: proc { Repos::AuctionContext::AuctionRepository.new }
 
-        # @param [Hash] opts Sets an allowed list of parameters, as well as some initial validations.
+        # Parameters specifying the required input types and fields.
         params do
           required(:auction_id).filled(:integer)
           required(:user_id).filled(:integer)
@@ -19,9 +32,7 @@ module AuctionFunCore
           end
         end
 
-        # Validation for auction.
-        # validate whether the given auction is valid at the database level.
-        # validate if the auction is open to receive bids
+        # Validates the auction's validity, kind, and status for receiving bids.
         rule(:auction_id) do |context:|
           context[:auction] ||= auction_repo.by_id(value)
 
@@ -40,9 +51,7 @@ module AuctionFunCore
           end
         end
 
-        # Validation for user.
-        # Validate whether the given user is valid at the database level.
-        # Validates if user has enough balance to bid.
+        # Validates the user's existence and ensures they have enough balance to bid.
         rule(:user_id) do |context:|
           context[:user] ||= user_repo.by_id(value)
 
@@ -59,7 +68,7 @@ module AuctionFunCore
 
         private
 
-        # Checks if user has enough balance to bid.
+        # Helper method to check if the user has sufficient balance to place a bid in a penny auction.
         def penny_auction_check_user_has_balance?(key, auction_bid_cents, balance_cents)
           key.failure(I18n.t("contracts.errors.custom.bids.insufficient_balance")) if balance_cents < auction_bid_cents
         end

data/lib/auction_fun_core/contracts/bid_context/create_bid_standard_contract.rb

@@ -3,12 +3,25 @@
 module AuctionFunCore
   module Contracts
     module BidContext
-      # Contract class to create new bids.
+      # This class validates the creation of new bids for standard-type auctions.
+      # It ensures the bid is placed by a valid user on a valid auction that is open for bids,
+      # and that the bid value meets or exceeds the minimum bid required by the auction.
+      #
+      # @example Creating a bid for a standard auction
+      #   contract = AuctionFunCore::Contracts::BidContext::CreateBidStandardContract.new
+      #   attributes = { auction_id: 1, user_id: 2, value_cents: 5000 }
+      #   result = contract.call(attributes)
+      #   if result.success?
+      #     puts "Bid created successfully."
+      #   else
+      #     puts "Failed to create bid: #{result.errors.to_h}"
+      #   end
       class CreateBidStandardContract < Contracts::ApplicationContract
+        # Repositories initialized to retrieve data for validation.
         option :user_repo, default: proc { Repos::UserContext::UserRepository.new }
         option :auction_repo, default: proc { Repos::AuctionContext::AuctionRepository.new }
 
-        # @param [Hash] opts Sets an allowed list of parameters, as well as some initial validations.
+        # Parameters specifying the required input types and fields.
         params do
           required(:auction_id).filled(:integer)
           required(:user_id).filled(:integer)
@@ -20,9 +33,7 @@ module AuctionFunCore
           end
         end
 
-        # Validation for auction.
-        # validate whether the given auction is valid at the database level.
-        # validate if the auction is open to receive bids
+        # Validates the auction's validity, kind, and status for receiving bids.
         rule(:auction_id) do |context:|
           context[:auction] ||= auction_repo.by_id(value)
 
@@ -41,22 +52,20 @@ module AuctionFunCore
           end
         end
 
-        # Validation for user.
-        # Validate whether the given user is valid at the database level.
+        # Validates the user's existence in the database.
         rule(:user_id) do |context:|
           context[:user] ||= user_repo.by_id(value)
           key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:user]
         end
 
-        # Validation for value bid.
-        # must be greater than or equal to the auction's minimal bid.
+        # Validates that the bid amount is greater than or equal to the auction's minimum bid.
         rule(:value_cents) do |context:|
           standard_auction_valid_bid?(key, value, context[:auction].minimal_bid_cents)
         end
 
         private
 
-        # Checks if the bid amount is greather than or equal to minimum bid.
+        # Helper method to check if the bid amount meets the minimum required bid.
         def standard_auction_valid_bid?(key, value_cents, minimal_bid_cents)
           return if value_cents >= minimal_bid_cents
 

data/lib/auction_fun_core/contracts/staff_context/authentication_contract.rb

@@ -3,12 +3,27 @@
 module AuctionFunCore
   module Contracts
     module StaffContext
-      # Contract class to authenticate staff.
+      # This class is designed to authenticate staff members.
+      # It validates the login and password, checking their format and verifying them against the database records.
+      #
+      # @example Authenticating a staff member
+      #   contract = AuctionFunCore::Contracts::StaffContext::AuthenticationContract.new
+      #   attributes = { login: 'staff@example.com', password: 'securePassword123' }
+      #   result = contract.call(attributes)
+      #   if result.success?
+      #     puts "Authentication successful."
+      #   else
+      #     puts "Authentication failed: #{result.errors.to_h}"
+      #   end
+      #
       class AuthenticationContract < ApplicationContract
+        # Scope for internationalization (i18n) entries specific to errors in this contract.
         I18N_SCOPE = "contracts.errors.custom.default"
 
+        # Repositories initialized to retrieve data for validation.
         option :staff_repository, default: proc { Repos::StaffContext::StaffRepository.new }
 
+        # Parameters specifying the required input types and fields.
         params do
           required(:login)
           required(:password)
@@ -18,12 +33,11 @@ module AuctionFunCore
           end
         end
 
+        # Additional rules for validating the format of login and password.
         rule(:login).validate(:login_format)
         rule(:password).validate(:password_format)
 
-        # Validation for login.
-        # Searches for the staff in the database from the login, and, if found,
-        # compares the entered password.
+        # Validates the presence of the staff member in the database and checks if the password matches.
         rule do |context:|
           next if (rule_error?(:login) || schema_error?(:login)) || (rule_error?(:password) || schema_error?(:password))
 

data/lib/auction_fun_core/contracts/staff_context/registration_contract.rb

@@ -3,13 +3,27 @@
 module AuctionFunCore
   module Contracts
     module StaffContext
-      # Contract class to create new staff.
+      # This class is designed to create staff members.
+      # It validates the parameters, ensuring their format and uniqueness.
+      #
+      # @example Registering a new staff member
+      #   contract = AuctionFunCore::Contracts::StaffContext::RegistrationContract.new
+      #   attributes = { name: 'John Doe', email: 'john.doe@example.com', phone: '1234567890' }
+      #   result = contract.call(attributes)
+      #   if result.success?
+      #     puts "Staff member registered successfully."
+      #   else
+      #     puts "Failed to register staff member: #{result.errors.to_h}"
+      #   end
+      #
       class RegistrationContract < ApplicationContract
+        # Scope for internationalization (i18n) entries specific to errors in this contract.
         I18N_SCOPE = "contracts.errors.custom.default"
 
+        # Repositories initialized to retrieve data for validation.
         option :staff_repository, default: proc { Repos::StaffContext::StaffRepository.new }
 
-        # @param [Hash] opts Sets an allowed list of parameters, as well as some initial validations.
+        # Parameters specifying the required input types and fields.
         params do
           required(:name)
           required(:email)
@@ -19,27 +33,25 @@ module AuctionFunCore
             result.to_h.compact
           end
 
-          # Normalize and add default values
+          # Normalizes and adds default values after coercion.
           after(:value_coercer) do |result|
             result.update(email: result[:email].strip.downcase) if result[:email]
             result.update(phone: result[:phone].tr_s("^0-9", "")) if result[:phone]
           end
         end
 
+        # Validates the format of the staff member's name.
         rule(:name).validate(:name_format)
 
-        # Validation for email.
-        # It must validate the format and uniqueness in the database.
+        # It ensures email format and checks for uniqueness in the database.
         rule(:email).validate(:email_format)
         rule(:email) do
-          # Email should be unique on database
           if !rule_error?(:email) && staff_repository.exists?(email: value)
             key.failure(I18n.t(:taken, scope: I18N_SCOPE))
           end
         end
 
-        # Validation for phone.
-        # It must validate the format and uniqueness in the database.
+        # It ensures phone format and checks for uniqueness in the database.
         rule(:phone).validate(:phone_format)
         rule(:phone) do
           if !rule_error?(:phone) && staff_repository.exists?(phone: value)

data/lib/auction_fun_core/contracts/user_context/authentication_contract.rb

@@ -3,12 +3,27 @@
 module AuctionFunCore
   module Contracts
     module UserContext
-      # Contract class to authenticate users.
+      # This class is designed to authenticate users.
+      # It verifies the provided login credentials against stored user data in the system.
+      #
+      # @example Authenticating a user
+      #   contract = AuctionFunCore::Contracts::UserContext::AuthenticationContract.new
+      #   attributes = { login: 'example_user', password: 'securePassword123' }
+      #   result = contract.call(attributes)
+      #   if result.success?
+      #     puts "User authenticated successfully."
+      #   else
+      #     puts "Authentication failed: #{result.errors.to_h}"
+      #   end
+      #
       class AuthenticationContract < ApplicationContract
+        # Scope for internationalization (i18n) entries specific to errors in this contract.
         I18N_SCOPE = "contracts.errors.custom.default"
 
+        # Repositories initialized to retrieve data for validation.
         option :user_repository, default: proc { Repos::UserContext::UserRepository.new }
 
+        # Parameters specifying the required input types and fields.
         params do
           required(:login)
           required(:password)
@@ -18,12 +33,11 @@ module AuctionFunCore
           end
         end
 
+        # Additional rules for validating the format of login and password.
         rule(:login).validate(:login_format)
         rule(:password).validate(:password_format)
 
-        # Validation for login.
-        # Searches for the user in the database from the login, and, if found,
-        # compares the entered password.
+        # Validates the presence of the user in the database and checks if the password matches.
         rule do |context:|
           next if (rule_error?(:login) || schema_error?(:login)) || (rule_error?(:password) || schema_error?(:password))
 

data/lib/auction_fun_core/contracts/user_context/email_confirmation_contract.rb

@@ -3,12 +3,27 @@
 module AuctionFunCore
   module Contracts
     module UserContext
-      # Contract class responsible for validating the confirmation token for email.
+      # This class provides validation for confirming email addresses.
+      # It verifies the provided email confirmation token against stored user data in the system.
+      #
+      # @example Confirming an email address
+      #   contract = AuctionFunCore::Contracts::UserContext::EmailConfirmationContract.new
+      #   attributes = { email_confirmation_token: 'example_token' }
+      #   result = contract.call(attributes)
+      #   if result.success?
+      #     puts "Email address enabled for confirmation."
+      #   else
+      #     puts "Failed to confirm email address: #{result.errors.to_h}"
+      #   end
+      #
       class EmailConfirmationContract < ApplicationContract
+        # Scope for internationalization (i18n) entries specific to errors in this contract.
         I18N_SCOPE = "contracts.errors.custom.default"
 
+        # Repositories initialized to retrieve data for validation.
         option :user_repository, default: proc { Repos::UserContext::UserRepository.new }
 
+        # Parameters specifying the required input types and fields.
         params do
           required(:email_confirmation_token)
 
@@ -17,7 +32,6 @@ module AuctionFunCore
           end
         end
 
-        # Validation for email_confirmation_token.
         # Searches for the user in the database from the email_confirmation_token
         rule do |context:|
           next if schema_error?(:email_confirmation_token)
@@ -29,6 +43,7 @@ module AuctionFunCore
           key(:email_confirmation_token).failure(I18n.t("not_found", scope: I18N_SCOPE))
         end
 
+        # Additional validation to check if the user account associated with the token is active.
         rule do |context:|
           next if context[:user].blank? || context[:user].active?
 

data/lib/auction_fun_core/contracts/user_context/phone_confirmation_contract.rb

@@ -3,12 +3,27 @@
 module AuctionFunCore
   module Contracts
     module UserContext
-      # Contract class responsible for validating the confirmation token for phone number.
+      # This class provides validation for confirming phone numbers.
+      # It verifies the provided phone confirmation token against stored user data in the system.
+      #
+      # @example Confirming a phone number
+      #   contract = AuctionFunCore::Contracts::UserContext::PhoneConfirmationContract.new
+      #   attributes = { phone_confirmation_token: 'example_token' }
+      #   result = contract.call(attributes)
+      #   if result.success?
+      #     puts "Phone number enabled for confirmation."
+      #   else
+      #     puts "Failed to confirm phone number: #{result.errors.to_h}"
+      #   end
+      #
       class PhoneConfirmationContract < ApplicationContract
+        # Scope for internationalization (i18n) entries specific to errors in this contract.
         I18N_SCOPE = "contracts.errors.custom.default"
 
+        # Repositories initialized to retrieve data for validation.
         option :user_repository, default: proc { Repos::UserContext::UserRepository.new }
 
+        # Parameters specifying the required input types and fields.
         params do
           required(:phone_confirmation_token)
 
@@ -17,7 +32,6 @@ module AuctionFunCore
           end
         end
 
-        # Validation for token_confirmation_token.
         # Searches for the user in the database from the phone_confirmation_token
         rule do |context:|
           next if schema_error?(:phone_confirmation_token)
@@ -29,6 +43,7 @@ module AuctionFunCore
           key(:phone_confirmation_token).failure(I18n.t("not_found", scope: I18N_SCOPE))
         end
 
+        # Additional validation to check if the user account associated with the token is active.
         rule do |context:|
           next if context[:user].blank? || context[:user].active?
 

data/lib/auction_fun_core/contracts/user_context/registration_contract.rb

@@ -3,13 +3,33 @@
 module AuctionFunCore
   module Contracts
     module UserContext
-      # Contract class to create new users.
+      # This class is designed to create new users.
+      # It validates the parameters, ensuring their format and uniqueness.
+      #
+      # @example Registering a new staff member
+      #   contract = AuctionFunCore::Contracts::StaffContext::RegistrationContract.new
+      #   attributes = {
+      #     name: 'John Doe',
+      #     email: 'john.doe@example.com',
+      #     phone: '1234567890'
+      #     password: 'password',
+      #     password_confirmation: 'password'
+      #   }
+      #   result = contract.call(attributes)
+      #   if result.success?
+      #     puts "New user registered successfully."
+      #   else
+      #     puts "Failed to register new user: #{result.errors.to_h}"
+      #   end
+      #
       class RegistrationContract < ApplicationContract
+        # Scope for internationalization (i18n) entries specific to errors in this contract.
         I18N_SCOPE = "contracts.errors.custom.default"
 
+        # Repositories initialized to retrieve data for validation.
         option :user_repository, default: proc { Repos::UserContext::UserRepository.new }
 
-        # @param [Hash] opts Sets an allowed list of parameters, as well as some initial validations.
+        # Parameters specifying the required input types and fields.
         params do
           required(:name)
           required(:email)
@@ -21,17 +41,17 @@ module AuctionFunCore
             result.to_h.compact
           end
 
-          # Normalize and add default values
+          # Normalizes and adds default values after coercion.
           after(:value_coercer) do |result|
             result.update(email: result[:email].strip.downcase) if result[:email]
             result.update(phone: result[:phone].tr_s("^0-9", "")) if result[:phone]
           end
         end
 
+        # Validates the format of the user's name.
         rule(:name).validate(:name_format)
 
-        # Validation for email.
-        # It must validate the format and uniqueness in the database.
+        # It ensures email format and checks for uniqueness in the database.
         rule(:email).validate(:email_format)
         rule(:email) do
           # Email should be unique on database
@@ -40,8 +60,7 @@ module AuctionFunCore
           end
         end
 
-        # Validation for phone.
-        # It must validate the format and uniqueness in the database.
+        # It ensures phone format and checks for uniqueness in the database.
         rule(:phone).validate(:phone_format)
         rule(:phone) do
           if !rule_error?(:phone) && user_repository.exists?(phone: value)
@@ -49,7 +68,6 @@ module AuctionFunCore
           end
         end
 
-        # Validation for password.
         # Check if the confirmation matches the password.
         rule(:password).validate(:password_format)
         rule(:password, :password_confirmation) do

data/lib/auction_fun_core/entities/auction.rb

@@ -2,16 +2,66 @@
 
 module AuctionFunCore
   module Entities
-    # Auction Relations class. This return simple objects with attribute readers
-    # to represent data in your auction.
+    ##
+    # Defines the Auction class as Entity. It appears to be a simple data structure
+    # class representing auction-related information.
     class Auction < ROM::Struct
+      # Retrieves the initial bid amount for an auction as a Money object.
+      #
+      # This method creates and returns a new Money object that represents the initial bid
+      # amount required to start bidding in the auction. It utilizes `initial_bid_cents` and
+      # `initial_bid_currency` attributes to construct the Money object, ensuring that the amount
+      # is correctly represented in the specified currency.
+      #
+      # @return [Money] Returns a Money object representing the initial bid amount with the specified currency.
       def initial_bid
         Money.new(initial_bid_cents, initial_bid_currency)
       end
 
+      # Retrieves the minimal bid amount for an auction as a Money object.
+      #
+      # This method creates and returns a new Money object that represents the minimal bid
+      # amount required to participate in the auction. It uses `minimal_bid_cents` and
+      # `minimal_bid_currency` attributes to construct the Money object.
+      #
+      # @return [Money] Returns a Money object representing the minimal bid amount with the appropriate currency.
       def minimal_bid
         Money.new(minimal_bid_cents, minimal_bid_currency)
       end
+
+      # Checks if an auction has a winner.
+      #
+      # This method determines if an auction has a winner based on the presence of a `winner_id`.
+      # It returns true if the `winner_id` is present, indicating that the auction has concluded
+      # with a winning bidder.
+      #
+      # @return [Boolean] Returns `true` if there is a winner for the auction, otherwise returns `false`.
+      def winner?
+        winner_id.present?
+      end
+
+      # Checks if an auction has already started.
+      #
+      # This method determines if an auction has begun based on its status and by comparing
+      # the auction's start time (`started_at`) with the current time. An auction is considered
+      # started if it is no longer scheduled (i.e., its status is not "scheduled") and
+      # the start time (`started_at`) is equal to or before the current time.
+      # @return [Boolean] Returns `true` if the auction has already started, otherwise returns `false`.
+      def started?
+        status != "scheduled" && Time.current > started_at
+      end
+
+      # Checks if an auction has not started yet.
+      #
+      # This method verifies if an auction is still in the "scheduled" status and whether
+      # its start time (`started_at`) is still in the future compared to the current time.
+      # The auction is considered not started if it is scheduled and the start time
+      # has not yet been reached.
+      #
+      # @return [Boolean] Returns `true` if the auction has not started yet, otherwise returns `false`.
+      def not_started?
+        status == "scheduled" && Time.current <= started_at
+      end
     end
   end
 end