<?php

namespace Modules\Core\Shipping\Contracts;

use Illuminate\Support\Collection;
use Modules\Core\Shipping\DTOs\TrackingCheckpoint;
use Modules\Core\Shipping\Models\Shipment;

/**
 * Optional capability for carriers that expose shipment tracking. Carriers
 * without a tracking API simply don't implement it.
 */
interface SupportsTracking
{
    /**
     * Return the shipment's known checkpoints from the carrier — as many
     * as the carrier's API returns in one call, not just the latest one.
     * Deduplication against what's already stored happens elsewhere.
     *
     * @return Collection<int, TrackingCheckpoint>
     */
    public function trackShipment(Shipment $shipment): Collection;
}