auction_fun_core 0.8.7 → 0.8.10

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

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

@@ -5,13 +5,29 @@ module AuctionFunCore
     module AuctionContext
       module PostAuction
         ##
-        # Operation class for finish auctions.
+        # 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)
 
@@ -20,7 +36,12 @@ module AuctionFunCore
             Dry::Matcher::ResultMatcher.call(operation, &block)
           end
 
-          ## @todo Add doc
+          ##
+          # 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)
 
@@ -33,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 = winner_contract.call(attributes)
 
@@ -41,6 +68,13 @@ module AuctionFunCore
             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

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

data/lib/auction_fun_core/operations/auction_context/processor/finish/closed_operation.rb

@@ -7,7 +7,7 @@ module AuctionFunCore
         module Finish
           ##
           # Operation class for finalizing a closed auction.
-          # By default, this change auction status from 'running' to 'finished'.
+          # By default, this changes the auction status from 'running' to 'finished'.
           #
           class ClosedOperation < AuctionFunCore::Operations::Base
             include Import["repos.auction_context.auction_repository"]
@@ -15,7 +15,21 @@ module AuctionFunCore
             include Import["workers.operations.auction_context.post_auction.winner_operation_job"]
             include Import["workers.operations.auction_context.post_auction.participant_operation_job"]
 
-            # @todo Add custom doc
+            ##
+            # Executes the closed operation with the provided attributes.
+            #
+            # @param attributes [Hash] The attributes for the closed operation.
+            # @option attributes auction_id [Integer] The ID of the auction.
+            # @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 }
+            #
+            #   AuctionFunCore::Operations::AuctionContext::Processor::Finish::ClosedOperation.call(attributes) do |result|
+            #     result.success { |auction| puts "Finished closed auction sucessfully! #{auction.to_h}" }
+            #     result.failure { |failure| puts "Failed to finished closed auction: #{failure.errors.to_h}"}
+            #   end
             def self.call(attributes, &block)
               operation = new.call(attributes)
 
@@ -24,10 +38,27 @@ module AuctionFunCore
               Dry::Matcher::ResultMatcher.call(operation, &block)
             end
 
-            # It only performs the basic processing of completing an auction.
-            # It just changes the status at the database level and triggers the finished event.
-            # @param auction_id [Integer] Auction ID
-            # @return [Dry::Monads::Result::Success, Dry::Monads::Result::Failure]
+            ##
+            # Performs the closing of a closed auction.
+            #
+            # @param attributes [Hash] The attributes for the closed operation.
+            # @option attributes auction_id [Integer] The ID of the auction.
+            # @return [Dry::Monads::Result] The result of the operation.
+            #
+            # @example
+            #   attributes = { auction_id: 123 }
+            #
+            #   operation = AuctionFunCore::Operations::AuctionContext::Processor::Finish::ClosedOperation.call(attributes)
+            #
+            #   if operation.success?
+            #     auction = operation.success
+            #     puts "Finished closed auction sucessfully! #{auction.to_h}"
+            #   end
+            #
+            #   if operation.failure?
+            #     failure = operation.failure
+            #     puts "Failed to finished closed auction: #{failure.errors.to_h}"
+            #   end
             def call(attributes)
               auction = yield validate_contract(attributes)
               summary = yield load_closed_auction_winners_and_participants(auction.id)
@@ -50,10 +81,13 @@ module AuctionFunCore
 
             private
 
-            # Calls the finish contract class to perform the validation
-            # of the informed attributes.
-            # @param attributes [Hash] auction attributes
-            # @return [Dry::Monads::Result::Success, Dry::Monads::Result::Failure]
+            ##
+            # 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 = closed_contract.call(attributes)
 
@@ -62,12 +96,25 @@ module AuctionFunCore
               Success(contract.context[:auction])
             end
 
+            ##
+            # Loads the winners and participants of the closed auction.
+            #
+            # @param auction_id [Integer] The ID of the auction.
+            # @return [Dry::Monads::Result] The result of loading the winners and participants.
+            #
             def load_closed_auction_winners_and_participants(auction_id)
               summary = relation.load_closed_auction_winners_and_participants(auction_id).first
 
               Success(summary)
             end
 
+            ##
+            # Updates the attributes of the finished auction.
+            #
+            # @param auction [Auction] The auction object.
+            # @param summary [Summary] The summary of winners and participants.
+            # @return [Dry::Monads::Result] The result of updating the attributes.
+            #
             def update_finished_auction(auction, summary)
               attrs = {status: "finished"}
               attrs[:winner_id] = summary.winner_id if summary.winner_id.present?
@@ -75,20 +122,45 @@ module AuctionFunCore
               Success(attrs)
             end
 
+            ##
+            # Retrieves the relation.
+            #
+            # @return [ROM::Relation] The relation object.
+            #
             def relation
               AuctionFunCore::Application[:container].relations[:auctions]
             end
 
+            ##
+            # Executes the winner operation asynchronously.
+            #
+            # @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 executing the operation.
+            #
             def winner_operation(auction_id, winner_id)
               return Success() if winner_id.blank?
 
               Success(winner_operation_job.class.perform_async(auction_id, winner_id))
             end
 
+            ##
+            # Executes the participant operation asynchronously.
+            #
+            # @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 executing the operation.
+            #
             def participant_operation(auction_id, participant_id)
               Success(participant_operation_job.class.perform_async(auction_id, participant_id))
             end
 
+            ##
+            # Publishes the auction finish event.
+            #
+            # @param auction [ROM::Struct::Auction] The auction object.
+            # @return [void]
+            #
             def publish_auction_finish_event(auction)
               Application[:event].publish("auctions.finished", auction.to_h)
             end

data/lib/auction_fun_core/operations/auction_context/processor/finish/penny_operation.rb

@@ -7,7 +7,7 @@ module AuctionFunCore
         module Finish
           ##
           # Operation class for finalizing a penny auction.
-          # By default, this change auction status from 'running' to 'finished'.
+          # By default, this changes the auction status from 'running' to 'finished'.
           #
           class PennyOperation < AuctionFunCore::Operations::Base
             include Import["repos.auction_context.auction_repository"]
@@ -15,7 +15,21 @@ module AuctionFunCore
             include Import["workers.operations.auction_context.post_auction.winner_operation_job"]
             include Import["workers.operations.auction_context.post_auction.participant_operation_job"]
 
-            # @todo Add custom doc
+            ##
+            # Executes the penny operation with the provided attributes.
+            #
+            # @param attributes [Hash] The attributes for the penny operation.
+            # @option attributes auction_id [Integer] The ID of the auction.
+            # @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 }
+            #
+            #   AuctionFunCore::Operations::AuctionContext::Processor::Finish::PennyOperation.call(attributes) do |result|
+            #     result.success { |auction| puts "Finished penny auction sucessfully! #{auction.to_h}" }
+            #     result.failure { |failure| puts "Failed to finished penny auction: #{failure.errors.to_h}"}
+            #   end
             def self.call(attributes, &block)
               operation = new.call(attributes)
 
@@ -24,10 +38,27 @@ module AuctionFunCore
               Dry::Matcher::ResultMatcher.call(operation, &block)
             end
 
-            # It only performs the basic processing of completing an auction.
-            # It just changes the status at the database level and triggers the finished event.
-            # @param auction_id [Integer] Auction ID
-            # @return [Dry::Monads::Result::Success, Dry::Monads::Result::Failure]
+            ##
+            # Performs the closing of a penny auction.
+            #
+            # @param attributes [Hash] The attributes for the penny operation.
+            # @option attributes auction_id [Integer] The ID of the auction.
+            # @return [Dry::Monads::Result] The result of the operation.
+            #
+            # @example
+            #   attributes = { auction_id: 123 }
+            #
+            #   operation = AuctionFunCore::Operations::AuctionContext::Processor::Finish::PennyOperation.call(attributes)
+            #
+            #   if operation.success?
+            #     auction = operation.success
+            #     puts "Finished penny auction sucessfully! #{auction.to_h}"
+            #   end
+            #
+            #   if operation.failure?
+            #     failure = operation.failure
+            #     puts "Failed to finished penny auction: #{failure.errors.to_h}"
+            #   end
             def call(attributes)
               auction = yield validate_contract(attributes)
               summary = yield load_penny_auction_winners_and_participants(auction.id)
@@ -50,10 +81,12 @@ module AuctionFunCore
 
             private
 
-            # Calls the finish contract class to perform the validation
-            # of the informed attributes.
-            # @param attributes [Hash] auction attributes
-            # @return [Dry::Monads::Result::Success, Dry::Monads::Result::Failure]
+            ##
+            # 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 = penny_contract.call(attributes)
 
@@ -62,12 +95,25 @@ module AuctionFunCore
               Success(contract.context[:auction])
             end
 
+            ##
+            # Loads the winners and participants of the penny auction.
+            #
+            # @param auction_id [Integer] The ID of the auction.
+            # @return [Dry::Monads::Result] The result of loading the winners and participants.
+            #
             def load_penny_auction_winners_and_participants(auction_id)
               summary = relation.load_penny_auction_winners_and_participants(auction_id).first
 
               Success(summary)
             end
 
+            ##
+            # Updates the attributes of the finished auction.
+            #
+            # @param auction [ROM::Struct::Auction] The auction object.
+            # @param summary [ROM::OpenStruct] The summary of winners and participants.
+            # @return [Dry::Monads::Result] The result of updating the attributes.
+            #
             def update_finished_auction(auction, summary)
               attrs = {status: "finished"}
               attrs[:winner_id] = summary.winner_id if summary.winner_id.present?
@@ -75,20 +121,45 @@ module AuctionFunCore
               Success(attrs)
             end
 
+            ##
+            # Retrieves the relation.
+            #
+            # @return [ROM::Relation] The relation object.
+            #
             def relation
               AuctionFunCore::Application[:container].relations[:auctions]
             end
 
+            ##
+            # Executes the winner operation asynchronously.
+            #
+            # @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 executing the operation.
+            #
             def winner_operation(auction_id, winner_id)
               return Success() if winner_id.blank?
 
               Success(winner_operation_job.class.perform_async(auction_id, winner_id))
             end
 
+            ##
+            # Executes the participant operation asynchronously.
+            #
+            # @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 executing the operation.
+            #
             def participant_operation(auction_id, participant_id)
               Success(participant_operation_job.class.perform_async(auction_id, participant_id))
             end
 
+            ##
+            # Publishes the auction finish event.
+            #
+            # @param auction [ROM::Struct::Auction] The auction object.
+            # @return [void]
+            #
             def publish_auction_finish_event(auction)
               Application[:event].publish("auctions.finished", auction.to_h)
             end