auction_fun_core 0.8.7 → 0.8.9

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,22 +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
-      INQUIRER_ATTRIBUTES = Relations::Auctions::STATUSES.values.freeze
-
+      # 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

data/lib/auction_fun_core/entities/bid.rb

@@ -2,8 +2,9 @@
 
 module AuctionFunCore
   module Entities
-    # Bid Relations class. This return simple objects with attribute readers
-    # to represent data in your bid.
+    ##
+    # Defines the Bid class as Entity. It appears to be a simple data structure
+    # class representing bid-related information.
     class Bid < ROM::Struct
     end
   end

data/lib/auction_fun_core/entities/staff.rb

@@ -2,17 +2,30 @@
 
 module AuctionFunCore
   module Entities
-    # Staff Relations class. This return simple objects with attribute readers
-    # to represent data in your staff.
+    ##
+    # Defines the Staff class as Entity. It appears to be a simple data structure
+    # class representing staff-related information.
     class Staff < ROM::Struct
+      ##
+      # Checks if the staff is active.
+      #
+      # @return [Boolean] True if the staff is active, otherwise false.
       def active?
         active
       end
 
+      ##
+      # Checks if the staff is inactive.
+      #
+      # @return [Boolean] True if the staff is inactive, otherwise false.
       def inactive?
         !active
       end
 
+      ##
+      # Returns staff information excluding password digest.
+      #
+      # @return [Hash] Staff information.
       def info
         attributes.except(:password_digest)
       end

data/lib/auction_fun_core/entities/user.rb

@@ -2,33 +2,62 @@
 
 module AuctionFunCore
   module Entities
-    # User Relations class. This return simple objects with attribute readers
-    # to represent data in your user.
+    ##
+    # Defines the User class as Entity. It appears to be a simple data structure
+    # class representing user-related information.
     class User < ROM::Struct
+      ##
+      # Checks if the user is active.
+      #
+      # @return [Boolean] True if the user is active, otherwise false.
       def active?
         active
       end
 
+      ##
+      # Checks if the user is inactive.
+      #
+      # @return [Boolean] True if the user is inactive, otherwise false.
       def inactive?
         !active
       end
 
+      ##
+      # Checks if the user has been confirmed.
+      #
+      # @return [Boolean] True if the user is confirmed, otherwise false.
       def confirmed?
         confirmed_at.present?
       end
 
+      ##
+      # Checks if the user's email has been confirmed.
+      #
+      # @return [Boolean] True if the email is confirmed, otherwise false.
       def email_confirmed?
         email_confirmation_at.present?
       end
 
+      ##
+      # Checks if the user's phone has been confirmed.
+      #
+      # @return [Boolean] True if the phone is confirmed, otherwise false.
       def phone_confirmed?
         phone_confirmation_at.present?
       end
 
+      ##
+      # Returns user information excluding password digest.
+      #
+      # @return [Hash] User information.
       def info
         attributes.except(:password_digest)
       end
 
+      ##
+      # Returns the user's balance as a Money object.
+      #
+      # @return [Money] User's balance.
       def balance
         Money.new(balance_cents, balance_currency)
       end

data/lib/auction_fun_core/events/app.rb

@@ -2,23 +2,29 @@
 
 module AuctionFunCore
   module Events
-    # Event class to register business events on system.
+    ##
+    # Represents the main application class for registering business events in the system.
+    #
+    # This class includes Dry::Events::Publisher[:app] to enable event publishing functionality.
     # @see https://dry-rb.org/gems/dry-events/main/
     class App
-      # @!parser include Dry::Events::Publisher[:app]
       include Dry::Events::Publisher[:app]
 
+      # Registers events related to auctions.
       register_event("auctions.created")
       register_event("auctions.started")
       register_event("auctions.finished")
       register_event("auctions.paused")
       register_event("auctions.unpaused")
 
+      # Registers events related to bids.
       register_event("bids.created")
 
+      # Registers events related to staffs.
       register_event("staffs.authentication")
       register_event("staffs.registration")
 
+      # Registers events related to users.
       register_event("users.authentication")
       register_event("users.registration")
       register_event("users.confirmation")

data/lib/auction_fun_core/events/listener.rb

@@ -2,7 +2,10 @@
 
 module AuctionFunCore
   module Events
-    # Event class that can listen business events.
+    ##
+    # Represents a class that listens to business events and performs actions accordingly.
+    #
+    # This class defines methods to handle various events related to auctions, bids, staff, and users.
     # @see https://dry-rb.org/gems/dry-events/main/#event-listeners
     class Listener
       # Listener for to *auctions.created* event.
@@ -36,15 +39,15 @@ module AuctionFunCore
       end
 
       # Listener for to *bids.created* event.
-      # @param event [Integer] Auction ID
+      # @param event [ROM::Struct::Bid] Auction ID
       def on_bids_created(bid)
         logger("Create bid with: #{bid.to_h}")
       end
 
-      # Listener for to *staffs.authentication* event.
-      # @param attributes [Hash] Authentication attributes
-      # @option staff_id [Integer] Staff ID
-      # @option time [DateTime] Authentication time
+      # Listener for the *staffs.authentication* event.
+      # @param attributes [Hash] Authentication attributes.
+      # @option attributes staff_id [Integer] Staff ID.
+      # @option attributes time [DateTime] Authentication time.
       def on_staffs_authentication(attributes)
         logger("Staff #{attributes[:staff_id]} authenticated on: #{attributes[:time].iso8601}")
       end
@@ -61,26 +64,26 @@ module AuctionFunCore
         logger("New registered user: #{user.to_h}")
       end
 
-      # Listener for to *users.authentication* event.
-      # @param attributes [Hash] Authentication attributes
-      # @option user_id [Integer] User ID
-      # @option time [DateTime] Authentication time
+      # Listener for the *users.authentication* event.
+      # @param attributes [Hash] Authentication attributes.
+      # @option attributes user_id [Integer] User ID.
+      # @option attributes time [DateTime] Authentication time.
       def on_users_authentication(attributes)
         logger("User #{attributes[:user_id]} authenticated on: #{attributes[:time].iso8601}")
       end
 
-      # Listener for to *users.confirmation* event.
-      # @param attributes [Hash] Confirmation attributes
-      # @option user_id [Integer] User ID
-      # @option time [DateTime] Authentication time
+      # Listener for the *users.confirmation* event.
+      # @param attributes [Hash] Confirmation attributes.
+      # @option user_id [Integer] User ID.
+      # @option time [DateTime] Authentication time.
       def on_users_confirmation(attributes)
         logger("User #{attributes[:user_id]} confirmed at: #{attributes[:time].iso8601}")
       end
 
       private
 
-      # Append message to system log.
-      # @param message [String] the message
+      # Appends a message to the system log.
+      # @param message [String] The message.
       def logger(message)
         Application[:logger].info(message)
       end

data/lib/auction_fun_core/operations/auction_context/create_operation.rb

@@ -10,6 +10,7 @@ module AuctionFunCore
         include Import["repos.auction_context.auction_repository"]
         include Import["contracts.auction_context.create_contract"]
         include Import["workers.operations.auction_context.processor.start_operation_job"]
+        include Import["workers.operations.auction_context.pre_auction.auction_start_reminder_operation_job"]
 
         # @todo Add custom doc
         def self.call(attributes, &block)
@@ -27,6 +28,7 @@ module AuctionFunCore
           auction_repository.transaction do |_t|
             @auction = yield persist(values)
             yield scheduled_start_auction(@auction)
+            yield schedule_auction_notification(@auction)
             yield publish_auctions_created(@auction)
           end
 
@@ -63,15 +65,6 @@ module AuctionFunCore
           Success(auction_repository.create(result))
         end
 
-        # Triggers the publication of event *auctions.created*.
-        # @param auction [Hash] Auction persisted attributes
-        # @return [Dry::Monads::Result::Success]
-        def publish_auctions_created(auction)
-          Application[:event].publish("auctions.created", auction.to_h)
-
-          Success()
-        end
-
         # Calls the background job class that will schedule the start of the auction.
         # Added a small delay to perform operations (such as sending broadcasts and/or other operations).
         # @param auction [ROM::Struct::Auction]
@@ -81,6 +74,29 @@ module AuctionFunCore
 
           Success(start_operation_job.class.perform_at(perform_at, auction.id))
         end
+
+        # Schedules a notification to be sent to users one hour before the auction starts.
+        # The scheduling is only done if the start of the auction is more than one hour ahead of the current time,
+        # ensuring that there is sufficient time for the notification to be sent.
+        #
+        # @param auction [ROM::Struct::Auction]
+        # @return [String] sidekiq jid
+        def schedule_auction_notification(auction)
+          perform_time = auction.started_at - 1.hour
+
+          return Success() if perform_time <= Time.current
+
+          Success(auction_start_reminder_operation_job.class.perform_at(perform_time, auction.id))
+        end
+
+        # Triggers the publication of event *auctions.created*.
+        # @param auction [ROM::Struct::Auction]
+        # @return [Dry::Monads::Result::Success]
+        def publish_auctions_created(auction)
+          Application[:event].publish("auctions.created", auction.to_h)
+
+          Success()
+        end
       end
     end
   end

data/lib/auction_fun_core/operations/auction_context/post_auction/participant_operation.rb

@@ -5,13 +5,29 @@ module AuctionFunCore
     module AuctionContext
       module PostAuction
         ##
-        # Operation class for finish auctions.
+        # Operation class for managing participants in auctions.
         #
         class ParticipantOperation < AuctionFunCore::Operations::Base
           include Import["repos.user_context.user_repository"]
           include Import["contracts.auction_context.post_auction.participant_contract"]
           include Import["workers.services.mail.auction_context.post_auction.participant_mailer_job"]
 
+          ##
+          # Executes the participant operation with the provided attributes.
+          #
+          # @param attributes [Hash] The attributes for the winner operation.
+          # @option attributes auction_id [Integer] The ID of the auction.
+          # @option attributes participant_id [Integer] The participating user ID.
+          # @yield [Dry::Matcher::Evaluator] The block to handle the result of the operation.
+          # @return [Dry::Matcher::Evaluator] The result of the operation.
+          #
+          # @example
+          #   attributes = { auction_id: 123, participant_id: 123 }
+          #
+          #   AuctionFunCore::Operations::AuctionContext::PostAuction::ParticipantOperation.call(attributes) do |result|
+          #     result.success { |auction| puts "Participation operation completed successfully! #{auction.to_h}" }
+          #     result.failure { |failure| puts "Failed auction participation operation: #{failure.errors.to_h}"}
+          #   end
           def self.call(attributes, &block)
             operation = new.call(attributes)
 
@@ -20,8 +36,12 @@ module AuctionFunCore
             Dry::Matcher::ResultMatcher.call(operation, &block)
           end
 
-          ## @todo Add more actions
-          #   Send email to participant with auction statistics.
+          ##
+          # Executes the participant operation.
+          #
+          # @param attributes [Hash] The attributes for the participant operation.
+          # @return [Dry::Monads::Result] The result of the operation.
+          #
           def call(attributes)
             auction, participant = yield validate_contract(attributes)
 
@@ -34,6 +54,12 @@ module AuctionFunCore
 
           private
 
+          ##
+          # Validates the contract with the provided attributes.
+          #
+          # @param attributes [Hash] The attributes to validate.
+          # @return [Dry::Monads::Result] The result of the validation.
+          #
           def validate_contract(attributes)
             contract = participant_contract.call(attributes)
 
@@ -42,6 +68,13 @@ module AuctionFunCore
             Success([contract.context[:auction], contract.context[:participant]])
           end
 
+          ##
+          # Sends participant email with auction statistics and payment instructions.
+          #
+          # @param auction_id [Integer] The ID of the auction.
+          # @param participant_id [Integer] The ID of the participant.
+          # @return [Dry::Monads::Result] The result of sending the email.
+          #
           def send_participant_email_with_statistics_and_payment_instructions(auction_id, participant_id)
             Success(participant_mailer_job.class.perform_async(auction_id, participant_id))
           end