<?php

namespace App\Services\Carriers;

use App\Models\Order;

interface CarrierInterface
{
    /**
     * Create a shipment with the carrier
     *
     * @param Order $order
     * @param array $formData Additional form data from carrier config_schema
     * @return array Returns array with 'tracking_id', 'label_url', 'raw_response', 'metadata'
     */
    public function createShipment(Order $order, array $formData = []): array;

    /**
     * Generate shipping label URL
     *
     * @param string $trackingId
     * @return string|null
     */
    public function generateLabel(string $trackingId): ?string;

    /**
     * Track shipment status
     *
     * @param string $trackingId
     * @return array|null
     */
    public function track(string $trackingId): ?array;

    /**
     * Validate carrier configuration
     *
     * @param array $config
     * @return bool
     */
    public function validateConfig(array $config): bool;

    /**
     * Check delivery availability for a given pincode
     *
     * @param string $pincode
     * @return array Returns array with 'available' (bool) and 'message' (string)
     */
    public function checkDeliveryAvailability(string $pincode): array;
}