Feat: Adding Shippment Tracking

src/Shipping/Contracts/SupportsTracking.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Modules\Core\Shipping\Contracts;
+
+use Illuminate\Support\Collection;
+use Modules\Core\Shipping\DataTransferObjects\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;
+}