<?php

namespace App\Services\Auction;

interface AuctionProviderInterface
{
    /**
     * Get list of live and upcoming Japanese auction vehicles
     */
    public function getLiveAuctions(array $filters = []): array;

    /**
     * Get single auction vehicle by auction ID or lot number
     */
    public function getAuctionVehicle(string $auctionId): ?array;

    /**
     * Get inspection auction sheet image URL or base64 stream
     */
    public function getAuctionSheet(string $auctionId): ?string;

    /**
     * Get past auction sales history for a chassis number / model
     */
    public function getAuctionHistory(string $chassisNumber): array;

    /**
     * Place maximum authorized bid onto Japanese auction API
     */
    public function placeBid(string $auctionId, float $maxBidJpy, array $metadata = []): array;

    /**
     * Cancel an active bid on Japanese auction API
     */
    public function cancelBid(string $bidExternalId): bool;

    /**
     * Get real-time status of a submitted bid from Japanese auction API
     */
    public function getBidStatus(string $bidExternalId): array;

    /**
     * Get final result (Won / Lost / Passed / Hammer Price) for an auction lot
     */
    public function getAuctionResult(string $auctionId): array;
}
