auction_fun_core 0.8.7 → 0.8.10

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

@@ -7,7 +7,7 @@ module AuctionFunCore
         module Finish
           ##
           # Operation class for finalizing a standard auction.
-          # By default, this change auction status from 'running' to 'finished'.
+          # By default, this changes the auction status from 'running' to 'finished'.
           #
           class StandardOperation < 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 standard operation with the provided attributes.
+            #
+            # @param attributes [Hash] The attributes for the standard 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::StandardOperation.call(attributes) do |result|
+            #     result.success { |auction| puts "Finished standard auction sucessfully! #{auction.to_h}" }
+            #     result.failure { |failure| puts "Failed to finished standard auction: #{failure.errors.to_h}"}
+            #   end
             def self.call(attributes, &block)
               operation = new.call(attributes)
 
@@ -24,12 +38,27 @@ module AuctionFunCore
               Dry::Matcher::ResultMatcher.call(operation, &block)
             end
 
-            # TODO: update doc
-            # 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 attrs [Hash] auction attributes
-            # @option auction_id [Integer] Auction ID
-            # @return [Dry::Monads::Result::Success, Dry::Monads::Result::Failure]
+            ##
+            # Performs the closing of a standard auction.
+            #
+            # @param attributes [Hash] The attributes for the standard operation.
+            # @option attributes auction_id [Integer] The ID of the auction.
+            # @return [Dry::Monads::Result::Success, Dry::Monads::Result::Failure] The result of the operation.
+            #
+            # @example
+            #   attributes = { auction_id: 123 }
+            #
+            #   operation = AuctionFunCore::Operations::AuctionContext::Processor::Finish::StandardOperation.call(attributes)
+            #
+            #   if operation.success?
+            #     auction = operation.success
+            #     puts "Finished standard auction sucessfully! #{auction.to_h}"
+            #   end
+            #
+            #   if operation.failure?
+            #     failure = operation.failure
+            #     puts "Failed to finished standard auction: #{failure.errors.to_h}"
+            #   end
             def call(attributes)
               auction = yield validate_contract(attributes)
               summary = yield load_standard_auction_winners_and_participants(auction.id)
@@ -52,10 +81,12 @@ module AuctionFunCore
 
             private
 
-            # Calls the finish standard 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 = standard_contract.call(attributes)
 
@@ -64,12 +95,25 @@ module AuctionFunCore
               Success(contract.context[:auction])
             end
 
+            ##
+            # Loads the winners and participants of the standard auction.
+            #
+            # @param auction_id [Integer] The ID of the auction.
+            # @return [Dry::Monads::Result] The result of loading the winners and participants.
+            #
             def load_standard_auction_winners_and_participants(auction_id)
               summary = relation.load_standard_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?
@@ -77,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

data/lib/auction_fun_core/operations/auction_context/processor/pause_operation.rb

@@ -12,7 +12,21 @@ module AuctionFunCore
           include Import["repos.auction_context.auction_repository"]
           include Import["contracts.auction_context.processor.pause_contract"]
 
-          # @todo Add custom doc
+          ##
+          # Executes the pause operation with the provided attributes.
+          #
+          # @param attributes [Hash] The attributes for the pause 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::PauseOperation.call(attributes) do |result|
+          #     result.success { |auction| puts "Paused auction sucessfully! #{auction.to_h}" }
+          #     result.failure { |failure| puts "Failed to pause auction: #{failure.errors.to_h}"}
+          #   end
           def self.call(attributes, &block)
             operation = new.call(attributes)
 
@@ -21,6 +35,27 @@ module AuctionFunCore
             Dry::Matcher::ResultMatcher.call(operation, &block)
           end
 
+          ##
+          # Performing an auction pause
+          #
+          # @param attributes [Hash] The attributes for the pause operation.
+          # @option attributes auction_id [Integer] The ID of the auction.
+          # @return [Dry::Monads::Result::Success, Dry::Monads::Result::Failure] The result of the operation.
+          #
+          # @example
+          #   attributes = { auction_id: 123 }
+          #
+          #   operation = AuctionFunCore::Operations::AuctionContext::Processor::PauseOperation.call(attributes)
+          #
+          #   if operation.success?
+          #     auction = operation.success
+          #     puts "Paused auction sucessfully! #{auction.to_h}"
+          #   end
+          #
+          #   if operation.failure?
+          #     failure = operation.failure
+          #     puts "Failed to pause auction: #{failure.errors.to_h}"
+          #   end
           def call(attributes)
             attrs = yield validate(attributes)
 

data/lib/auction_fun_core/operations/auction_context/processor/unpause_operation.rb

@@ -12,7 +12,21 @@ module AuctionFunCore
           include Import["repos.auction_context.auction_repository"]
           include Import["contracts.auction_context.processor.unpause_contract"]
 
-          # @todo Add custom doc
+          ##
+          # Executes the unpause operation with the provided attributes.
+          #
+          # @param attributes [Hash] The attributes for the unpause 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::UnpauseOperation.call(attributes) do |result|
+          #     result.success { |auction| puts "Unpaused auction sucessfully! #{auction.to_h}" }
+          #     result.failure { |failure| puts "Failed to unpause auction: #{failure.errors.to_h}"}
+          #   end
           def self.call(attributes, &block)
             operation = new.call(attributes)
 
@@ -21,6 +35,27 @@ module AuctionFunCore
             Dry::Matcher::ResultMatcher.call(operation, &block)
           end
 
+          ##
+          # Performs the unpause of an auction.
+          #
+          # @param attributes [Hash] The attributes for the unpause operation.
+          # @option attributes auction_id [Integer] The ID of the auction.
+          # @return [Dry::Monads::Result::Success, Dry::Monads::Result::Failure] The result of the operation.
+          #
+          # @example
+          #   attributes = { auction_id: 123 }
+          #
+          #   operation = AuctionFunCore::Operations::AuctionContext::Processor::UnpauseOperation.call(attributes)
+          #
+          #   if operation.success?
+          #     auction = operation.success
+          #     puts "Unpaused auction sucessfully! #{auction.to_h}"
+          #   end
+          #
+          #   if operation.failure?
+          #     failure = operation.failure
+          #     puts "Failed to unpause auction: #{failure.errors.to_h}"
+          #   end
           def call(attributes)
             attrs = yield validate(attributes)
 

data/lib/auction_fun_core/relations/auctions.rb

@@ -40,12 +40,30 @@ module AuctionFunCore
       struct_namespace Entities
       auto_struct(true)
 
+      # Retrieves a paginated list of auctions along with related information.
+      # By default, it retrieves the first page with 10 auctions per page and includes information for the top 3 bidders.
+      #
+      # @param page [Integer] The page number to retrieve (default is 1).
+      # @param per_page [Integer] The number of auctions per page (default is 10).
+      # @param options [Hash] Additional options for customization (default is {bidders_count: 3}).
+      # @option options [Integer] :bidders_count The number of top bidders to include in the result (default is 3).
+      # @return [Array<Hash>] An array of hashes representing the auctions and related information.
+      # @example Retrieve the first page of auctions with 10 per page and include information for the top 3 bidders
+      #   all_auctions = all
+      #
+      # @example Retrieve the second page of auctions with 5 per page and include information for the top 5 bidders
+      #   all_auctions = all(2, 5, { bidders_count: 5 })
+      #
+      # @example Retrieve the third page of auctions with 15 per page and include information for the top 2 bidders
+      #   all_auctions = all(3, 15, { bidders_count: 2 })
+      #
+      # @raise [RuntimeError] if either `page` or `per_page` argument is not an integer.
       def all(page = 1, per_page = 10, options = {bidders_count: 3})
         raise "Invalid argument" unless page.is_a?(Integer) && per_page.is_a?(Integer)
 
         offset = ((page - 1) * per_page)
 
-        read("
+        sql = <<-SQL
           SELECT a.id, a.title, a.description, a.kind, a.status, a.started_at, a.finished_at, a.stopwatch, a.initial_bid_cents,
           (SELECT COUNT(*) FROM (SELECT * FROM bids WHERE bids.auction_id = a.id) dt) AS total_bids,
           CASE
@@ -69,17 +87,37 @@ module AuctionFunCore
           WHEN a.kind = 'closed' THEN
             json_build_object('minimal', (a.initial_bid_cents + (a.initial_bid_cents * 0.10))::int)
           END as bids
-        FROM auctions as a
-        LEFT JOIN LATERAL (SELECT * FROM bids WHERE auction_id = a.id ORDER BY value_cents DESC LIMIT #{options[:bidders_count]}) as bi ON a.id = bi.auction_id
-        LEFT JOIN users ON bi.user_id = users.id AND bi.auction_id = a.id
-        GROUP BY a.id
-        LIMIT #{per_page} OFFSET #{offset}")
+          FROM auctions as a
+          LEFT JOIN LATERAL (SELECT * FROM bids WHERE auction_id = a.id ORDER BY value_cents DESC LIMIT #{options[:bidders_count]}) as bi ON a.id = bi.auction_id
+          LEFT JOIN users ON bi.user_id = users.id AND bi.auction_id = a.id
+          GROUP BY a.id
+          LIMIT #{per_page} OFFSET #{offset}
+        SQL
+
+        read(sql)
       end
 
+      # Retrieves detailed information about a specific auction.
+      #
+      # @param auction_id [Integer] The ID of the auction to retrieve information for.
+      # @param options [Hash] Additional options for customization (default is {bidders_count: 3}).
+      # @option options [Integer] :bidders_count The number of top bidders to include in the result (default is 3).
+      # @return [Hash] A hash representing the auction and related information.
+      #
+      # @example Retrieve information for auction with ID 123
+      #   auction_info = info(123)
+      #
+      # @example Retrieve information for auction with ID 456 and include information for the top 5 bidders
+      #   auction_info = info(456, { bidders_count: 5 })
+      #
+      # @example Retrieve information for auction with ID 789 and include information for the top 2 bidders
+      #   auction_info = info(789, { bidders_count: 2 })
+      #
+      # @raise [RuntimeError] if `auction_id` argument is not an integer.
       def info(auction_id, options = {bidders_count: 3})
         raise "Invalid argument" unless auction_id.is_a?(Integer)
 
-        read("
+        sql = <<-SQL
           SELECT a.id, a.title, a.description, a.kind, a.status, a.started_at, a.finished_at, a.stopwatch, a.initial_bid_cents,
           (SELECT COUNT(*) FROM (SELECT * FROM bids WHERE bids.auction_id = #{auction_id}) dt) AS total_bids,
           CASE
@@ -103,11 +141,14 @@ module AuctionFunCore
           WHEN a.kind = 'closed' THEN
             json_build_object('minimal', (a.initial_bid_cents + (a.initial_bid_cents * 0.10))::int)
           END as bids
-        FROM auctions as a
-        LEFT JOIN LATERAL (SELECT * FROM bids WHERE auction_id = a.id ORDER BY value_cents DESC LIMIT #{options[:bidders_count]}) as bi ON a.id = bi.auction_id AND a.id = #{auction_id}
-        LEFT JOIN users ON bi.user_id = users.id AND bi.auction_id = a.id
-        WHERE a.id = #{auction_id}
-        GROUP BY a.id")
+          FROM auctions as a
+          LEFT JOIN LATERAL (SELECT * FROM bids WHERE auction_id = a.id ORDER BY value_cents DESC LIMIT #{options[:bidders_count]}) as bi ON a.id = bi.auction_id AND a.id = #{auction_id}
+          LEFT JOIN users ON bi.user_id = users.id AND bi.auction_id = a.id
+          WHERE a.id = #{auction_id}
+          GROUP BY a.id
+        SQL
+
+        read(sql)
       end
 
       # Retrieves the standard auction winner and other participating bidders for a specified auction.
@@ -125,22 +166,26 @@ module AuctionFunCore
       def load_standard_auction_winners_and_participants(auction_id)
         raise "Invalid argument" unless auction_id.is_a?(Integer)
 
-        read("SELECT a.id, a.kind, a.status, w.user_id AS winner_id, COALESCE(COUNT(b.id), 0) AS total_bids,
-          COALESCE(
-            ARRAY_REMOVE(ARRAY_AGG(DISTINCT b.user_id ORDER BY b.user_id), w.user_id), ARRAY[]::INT[]
-          ) AS participant_ids
-        FROM auctions a
-        LEFT JOIN bids b ON a.id = b.auction_id
-        LEFT JOIN (
-          SELECT auction_id, user_id, MAX(value_cents) AS value_cents
-          FROM bids
-          WHERE auction_id = #{auction_id}
-          GROUP BY auction_id, user_id
-          ORDER BY value_cents DESC
-          LIMIT 1
-        ) AS w ON a.id = w.auction_id
-        WHERE a.id = #{auction_id}
-        GROUP BY a.id, w.user_id")
+        sql = <<-SQL
+          SELECT a.id, a.kind, a.status, w.user_id AS winner_id, COALESCE(COUNT(b.id), 0) AS total_bids,
+            COALESCE(
+              ARRAY_REMOVE(ARRAY_AGG(DISTINCT b.user_id ORDER BY b.user_id), w.user_id), ARRAY[]::INT[]
+            ) AS participant_ids
+          FROM auctions a
+          LEFT JOIN bids b ON a.id = b.auction_id
+          LEFT JOIN (
+            SELECT auction_id, user_id, MAX(value_cents) AS value_cents
+            FROM bids
+            WHERE auction_id = #{auction_id}
+            GROUP BY auction_id, user_id
+            ORDER BY value_cents DESC
+            LIMIT 1
+          ) AS w ON a.id = w.auction_id
+          WHERE a.id = #{auction_id}
+          GROUP BY a.id, w.user_id
+        SQL
+
+        read(sql)
       end
 
       # Retrieves the penny auction winner and other participating bidders for a specified auction.
@@ -158,21 +203,25 @@ module AuctionFunCore
       def load_penny_auction_winners_and_participants(auction_id)
         raise "Invalid argument" unless auction_id.is_a?(Integer)
 
-        read("SELECT a.id, a.kind, a.status, w.user_id AS winner_id, COALESCE(COUNT(b.id), 0) AS total_bids,
-          COALESCE(
-            ARRAY_REMOVE(ARRAY_AGG(DISTINCT b.user_id ORDER BY b.user_id), w.user_id), ARRAY[]::INT[]
-          ) AS participant_ids
-        FROM auctions a
-        LEFT JOIN bids b ON a.id = b.auction_id
-        LEFT JOIN (
-          SELECT auction_id, user_id
-          FROM bids
-          WHERE auction_id = #{auction_id}
-          ORDER BY bids.created_at DESC
-          LIMIT 1
-        ) AS w ON a.id = w.auction_id
-        WHERE a.id = #{auction_id}
-        GROUP BY a.id, w.user_id")
+        sql = <<-SQL
+          SELECT a.id, a.kind, a.status, w.user_id AS winner_id, COALESCE(COUNT(b.id), 0) AS total_bids,
+            COALESCE(
+              ARRAY_REMOVE(ARRAY_AGG(DISTINCT b.user_id ORDER BY b.user_id), w.user_id), ARRAY[]::INT[]
+            ) AS participant_ids
+          FROM auctions a
+          LEFT JOIN bids b ON a.id = b.auction_id
+          LEFT JOIN (
+            SELECT auction_id, user_id
+            FROM bids
+            WHERE auction_id = #{auction_id}
+            ORDER BY bids.created_at DESC
+            LIMIT 1
+          ) AS w ON a.id = w.auction_id
+          WHERE a.id = #{auction_id}
+          GROUP BY a.id, w.user_id
+        SQL
+
+        read(sql)
       end
 
       # Retrieves the closed auction winner and other participating bidders for a specified auction.
@@ -190,70 +239,102 @@ module AuctionFunCore
       def load_closed_auction_winners_and_participants(auction_id)
         raise "Invalid argument" unless auction_id.is_a?(Integer)
 
-        read("SELECT a.id, a.kind, a.status, w.user_id AS winner_id, COALESCE(COUNT(b.id), 0) AS total_bids,
-          COALESCE(
-            ARRAY_REMOVE(ARRAY_AGG(DISTINCT b.user_id ORDER BY b.user_id), w.user_id), ARRAY[]::INT[]
-          ) AS participant_ids
-        FROM auctions a
-        LEFT JOIN bids b ON a.id = b.auction_id
-        LEFT JOIN (
-          SELECT auction_id, user_id, MAX(value_cents) AS value_cents
-          FROM bids
-          WHERE auction_id = #{auction_id}
-          GROUP BY auction_id, user_id
-          ORDER BY value_cents DESC
-          LIMIT 1
-        ) AS w ON a.id = w.auction_id
-        WHERE a.id = #{auction_id}
-        GROUP BY a.id, w.user_id")
+        sql = <<-SQL
+          SELECT a.id, a.kind, a.status, w.user_id AS winner_id, COALESCE(COUNT(b.id), 0) AS total_bids,
+            COALESCE(
+              ARRAY_REMOVE(ARRAY_AGG(DISTINCT b.user_id ORDER BY b.user_id), w.user_id), ARRAY[]::INT[]
+            ) AS participant_ids
+          FROM auctions a
+          LEFT JOIN bids b ON a.id = b.auction_id
+          LEFT JOIN (
+            SELECT auction_id, user_id, MAX(value_cents) AS value_cents
+            FROM bids
+            WHERE auction_id = #{auction_id}
+            GROUP BY auction_id, user_id
+            ORDER BY value_cents DESC
+            LIMIT 1
+          ) AS w ON a.id = w.auction_id
+          WHERE a.id = #{auction_id}
+          GROUP BY a.id, w.user_id
+        SQL
+
+        read(sql)
       end
 
+      # Loads statistics for the winner of a specific auction.
+      #
+      # @param auction_id [Integer] The ID of the auction to load statistics for.
+      # @param winner_id [Integer] The ID of the winner to load statistics for.
+      # @return [Hash] A hash representing the statistics for the winner of the auction.
+      #
+      # @example Load statistics for the winner of auction with ID 123 and winner with ID 456
+      #   winner_stats = load_winner_statistics(123, 456)
+      #
+      # @raise [RuntimeError] if either `auction_id` or `winner_id` arguments are not integers.
       def load_winner_statistics(auction_id, winner_id)
         raise "Invalid argument" unless auction_id.is_a?(Integer) && winner_id.is_a?(Integer)
 
-        read("SELECT a.id, COUNT(b.id) AS auction_total_bids, MAX(b.value_cents) AS winner_bid,
-          date(a.finished_at) as auction_date,
-          (SELECT COUNT(*) FROM bids b2
-            WHERE b2.auction_id = #{auction_id}
-            AND b2.user_id = #{winner_id}
-          ) AS winner_total_bids
-        FROM auctions a
-        LEFT JOIN bids b ON a.id = b.auction_id AND a.id = #{auction_id}
-        LEFT JOIN users u ON u.id = b.user_id AND u.id = #{winner_id}
-        LEFT JOIN (
-          SELECT auction_id, user_id, MAX(value_cents) AS value_cents
-          FROM bids
-          WHERE auction_id = #{auction_id}
-          GROUP BY auction_id, user_id
-          ORDER BY value_cents DESC
-          LIMIT 1
-        ) AS w ON a.id = w.auction_id
-        WHERE a.id = #{auction_id}
-        GROUP BY a.id")
+        sql = <<-SQL
+          SELECT a.id, COUNT(b.id) AS auction_total_bids, MAX(b.value_cents) AS winner_bid,
+            date(a.finished_at) as auction_date,
+            (SELECT COUNT(*) FROM bids b2
+              WHERE b2.auction_id = #{auction_id}
+              AND b2.user_id = #{winner_id}
+            ) AS winner_total_bids
+          FROM auctions a
+          LEFT JOIN bids b ON a.id = b.auction_id AND a.id = #{auction_id}
+          LEFT JOIN users u ON u.id = b.user_id AND u.id = #{winner_id}
+          LEFT JOIN (
+            SELECT auction_id, user_id, MAX(value_cents) AS value_cents
+            FROM bids
+            WHERE auction_id = #{auction_id}
+            GROUP BY auction_id, user_id
+            ORDER BY value_cents DESC
+            LIMIT 1
+          ) AS w ON a.id = w.auction_id
+          WHERE a.id = #{auction_id}
+          GROUP BY a.id
+        SQL
+
+        read(sql)
       end
 
+      # Loads statistics for a participant in a specific auction.
+      #
+      # @param auction_id [Integer] The ID of the auction to load statistics for.
+      # @param participant_id [Integer] The ID of the participant to load statistics for.
+      # @return [Hash] A hash representing the statistics for the participant in the auction.
+      #
+      # @example Load statistics for the participant with ID 456 in auction with ID 123
+      #   participant_stats = load_participant_statistics(123, 456)
+      #
+      # @raise [RuntimeError] if either `auction_id` or `participant_id` arguments are not integers.
       def load_participant_statistics(auction_id, participant_id)
         raise "Invalid argument" unless auction_id.is_a?(Integer) && participant_id.is_a?(Integer)
 
-        read("SELECT a.id, COUNT(b.id) AS auction_total_bids, MAX(b.value_cents) AS winner_bid,
-          date(a.finished_at) as auction_date,
-          (SELECT COUNT(*) FROM bids b2
-            WHERE b2.auction_id = #{auction_id}
-            AND b2.user_id = #{participant_id}
-          ) AS winner_total_bids
-        FROM auctions a
-        LEFT JOIN bids b ON a.id = b.auction_id AND a.id = #{auction_id}
-        LEFT JOIN users u ON u.id = b.user_id AND u.id = #{participant_id}
-        LEFT JOIN (
-          SELECT auction_id, user_id, MAX(value_cents) AS value_cents
-          FROM bids
-          WHERE auction_id = #{auction_id}
-          GROUP BY auction_id, user_id
-          ORDER BY value_cents DESC
-          LIMIT 1
-        ) AS w ON a.id = w.auction_id
-        WHERE a.id = #{auction_id}
-        GROUP BY a.id")
+        sql = <<-SQL
+          SELECT a.id, COUNT(b.id) AS auction_total_bids, MAX(b.value_cents) AS winner_bid,
+            date(a.finished_at) as auction_date,
+            (SELECT COUNT(*) FROM bids b2
+              WHERE b2.auction_id = #{auction_id}
+              AND b2.user_id = #{participant_id}
+            ) AS winner_total_bids
+          FROM auctions a
+          LEFT JOIN bids b ON a.id = b.auction_id AND a.id = #{auction_id}
+          LEFT JOIN users u ON u.id = b.user_id AND u.id = #{participant_id}
+          LEFT JOIN (
+            SELECT auction_id, user_id, MAX(value_cents) AS value_cents
+            FROM bids
+            WHERE auction_id = #{auction_id}
+            GROUP BY auction_id, user_id
+            ORDER BY value_cents DESC
+            LIMIT 1
+          ) AS w ON a.id = w.auction_id
+          WHERE a.id = #{auction_id}
+          GROUP BY a.id
+        SQL
+
+        read(sql)
       end
     end
   end

data/lib/auction_fun_core/relations/bids.rb

@@ -23,6 +23,24 @@ module AuctionFunCore
 
       struct_namespace Entities
       auto_struct(true)
+
+      # Retrieves a list of unique user IDs who have placed bids in a specified auction.
+      # A participant in an auction is defined as a user who has placed one or more bids.
+      #
+      # @param auction_id [Integer] the ID of the auction.
+      # @return [Array<Integer>] Returns an array of unique user IDs who have participated in the auction.
+      # @raise [RuntimeError] Raises an error if the auction_id is not an integer.
+      def participants(auction_id)
+        raise "Invalid argument" unless auction_id.is_a?(Integer)
+
+        sql = <<-SQL
+          SELECT COALESCE(ARRAY_AGG(DISTINCT user_id), ARRAY[]::INT[]) AS participant_ids
+          FROM bids
+          WHERE auction_id = #{auction_id}
+        SQL
+
+        read(sql)
+      end
     end
   end
 end