auction_fun_core 0.8.5 → 0.8.9

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)
@@ -21,11 +22,13 @@ module AuctionFunCore
         end
 
         def call(attributes)
-          values = yield validate(attributes)
+          values = yield validate_contract(attributes)
+          values = yield assign_default_values(values)
 
           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
 
@@ -38,7 +41,7 @@ module AuctionFunCore
         # of the informed attributes.
         # @param attrs [Hash] auction attributes
         # @return [Dry::Monads::Result::Success, Dry::Monads::Result::Failure]
-        def validate(attrs)
+        def validate_contract(attrs)
           contract = create_contract.call(attrs)
 
           return Failure(contract.errors.to_h) if contract.failure?
@@ -46,6 +49,15 @@ module AuctionFunCore
           Success(contract.to_h)
         end
 
+        # By default, the auction status is set to 'scheduled'.
+        # @todo Refactor this method in the future to consider the status as of the auction start date.
+        # @param attrs [Hash] auction attributes
+        # @return [Dry::Monads::Result::Success]
+        def assign_default_values(attrs)
+          attrs[:status] = "scheduled"
+          Success(attrs)
+        end
+
         # Calls the auction repository class to persist the attributes in the database.
         # @param result [Hash] Auction validated attributes
         # @return [ROM::Struct::Auction]
@@ -53,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]
@@ -71,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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module AuctionFunCore
+  module Operations
+    module AuctionContext
+      module PostAuction
+        ##
+        # 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)
+
+            return operation unless block
+
+            Dry::Matcher::ResultMatcher.call(operation, &block)
+          end
+
+          ##
+          # 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)
+
+            user_repository.transaction do |_t|
+              yield send_participant_email_with_statistics_and_payment_instructions(auction.id, participant.id)
+            end
+
+            Success([auction, participant])
+          end
+
+          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)
+
+            return Failure(contract.errors.to_h) if contract.failure?
+
+            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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module AuctionFunCore
+  module Operations
+    module AuctionContext
+      module PostAuction
+        ##
+        # Operation class for managing winners in auctions.
+        #
+        class WinnerOperation < AuctionFunCore::Operations::Base
+          include Import["repos.user_context.user_repository"]
+          include Import["contracts.auction_context.post_auction.winner_contract"]
+          include Import["workers.services.mail.auction_context.post_auction.winner_mailer_job"]
+
+          ##
+          # Executes the winner 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 winner_id [Integer] The winning 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, winner_id: 123 }
+          #
+          #   AuctionFunCore::Operations::AuctionContext::PostAuction::WinnerOperation.call(attributes) do |result|
+          #     result.success { |auction| puts "Winner operation completed successfully! #{auction.to_h}" }
+          #     result.failure { |failure| puts "Failed auction winner operation: #{failure.errors.to_h}"}
+          #   end
+          def self.call(attributes, &block)
+            operation = new.call(attributes)
+
+            return operation unless block
+
+            Dry::Matcher::ResultMatcher.call(operation, &block)
+          end
+
+          ##
+          # Executes the winner operation.
+          #
+          # @param attributes [Hash] The attributes for the winner operation.
+          # @return [Dry::Monads::Result] The result of the operation.
+          #
+          def call(attributes)
+            auction, winner = yield validate_contract(attributes)
+
+            user_repository.transaction do |_t|
+              send_winner_email_with_statistics_and_payment_instructions(auction.id, winner.id)
+            end
+
+            Success([auction, winner])
+          end
+
+          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 = winner_contract.call(attributes)
+
+            return Failure(contract.errors.to_h) if contract.failure?
+
+            Success([contract.context[:auction], contract.context[:winner]])
+          end
+
+          ##
+          # Sends winner email with auction statistics and payment instructions.
+          #
+          # @param auction_id [Integer] The ID of the auction.
+          # @param winner_id [Integer] The ID of the winner.
+          # @return [Dry::Monads::Result] The result of sending the email.
+          #
+          def send_winner_email_with_statistics_and_payment_instructions(auction_id, winner_id)
+            Success(winner_mailer_job.class.perform_async(auction_id, winner_id))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auction_fun_core/operations/auction_context/pre_auction/auction_start_reminder_operation.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module AuctionFunCore
+  module Operations
+    module AuctionContext
+      module PreAuction
+        ##
+        # Operation class for sending a reminder email to a participant about the start of an auction.
+        #
+        class AuctionStartReminderOperation < AuctionFunCore::Operations::Base
+          include Import["repos.bid_context.bid_repository"]
+          include Import["contracts.auction_context.pre_auction.auction_start_reminder_contract"]
+          include Import["workers.services.mail.auction_context.pre_auction.auction_start_reminder_mailer_job"]
+
+          ##
+          # Executes the auction start reminder operation with the provided attributes.
+          #
+          # @param attributes [Hash] The attributes for the auction start reminder operation.
+          # @yield [Dry::Matcher::Evaluator] The block to handle the result of the operation.
+          # @return [Dry::Matcher::Evaluator] The result of the operation.
+          #
+          def self.call(attributes, &block)
+            operation = new.call(attributes)
+
+            return operation unless block
+
+            Dry::Matcher::ResultMatcher.call(operation, &block)
+          end
+
+          ##
+          # Executes the auction start reminder operation.
+          #
+          # @param attributes [Hash] The attributes for the auction start reminder operation.
+          # @return [Dry::Monads::Result] The result of the operation.
+          #
+          def call(attributes)
+            auction = yield validate_contract(attributes)
+            participant_ids = yield collect_current_auction_participants(auction.id)
+
+            bid_repository.transaction do |_t|
+              participant_ids.each do |participant_id|
+                yield send_auction_start_reminder_mailer_job(auction.id, participant_id)
+              end
+            end
+
+            Success([auction, participant_ids])
+          end
+
+          private
+
+          ##
+          # Validates the contract with the provided attributes.
+          #
+          # @param attributes [Hash] The attributes to validate.
+          # @option auction_id [Integer] The ID of the auction.
+          # @return [Dry::Monads::Result] The result of the validation.
+          #
+          def validate_contract(attributes)
+            contract = auction_start_reminder_contract.call(attributes)
+
+            return Failure(contract.errors.to_h) if contract.failure?
+
+            Success(contract.context[:auction])
+          end
+
+          ##
+          # Collects the participant IDs for the current auction.
+          #
+          # @param auction_id [Integer] The ID of the auction.
+          # @return [Dry::Monads::Result] The result of collecting the participant IDs.
+          #
+          def collect_current_auction_participants(auction_id)
+            Success(
+              AuctionFunCore::Application[:container]
+                .relations[:bids]
+                .participants(auction_id)
+                .one
+                .participant_ids.to_a
+            )
+          end
+
+          ##
+          # Sends the auction start reminder email to a participant.
+          #
+          # @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_auction_start_reminder_mailer_job(auction_id, participant_id)
+            Success(auction_start_reminder_mailer_job.class.perform_async(auction_id, participant_id))
+          end
+        end
+      end
+    end
+  end
+end