📄 LogisticsProviderInterface.php

<?php

namespace App\Contracts;

use App\Modules\Order\Models\Order;

/**
 * LogisticsProviderInterface
 *
 * Every courier / logistics provider implements this.
 * Phase 1: ManualCourierProvider (AWB entered by vendor manually).
 * Phase 2+: Shiprocket, Delhivery, Nepal custom courier.
 */
interface LogisticsProviderInterface
{
    public function getName(): string;
    public function getLabel(): string;

    /**
     * Check serviceability for a destination pin/zip code.
     */
    public function checkServiceability(string $pinCode, string $countryCode = 'NP'): bool;

    /**
     * Calculate shipping rate estimate.
     *
     * @return array{amount: float, currency: string, estimated_days: int}
     */
    public function getShippingRate(Order $order, string $serviceType = 'standard'): array;

    /**
     * Create a shipment and return tracking details.
     *
     * @return array{awb: string, tracking_url: string, label_url?: string}
     */
    public function createShipment(Order $order, array $options = []): array;

    /**
     * Fetch latest tracking status from the provider.
     *
     * @return array{status: string, location?: string, timestamp?: string, events?: array}
     */
    public function trackShipment(string $awbNumber): array;

    /**
     * Cancel a shipment (before dispatch).
     */
    public function cancelShipment(string $awbNumber): bool;
}