<?php
/**
 * SimplyIN Payment Module
 *
 * Interface for shipping module integrators that handle pickup point data
 * for different shipping providers (InPost, Orlen, DPD).
 */
declare(strict_types=1);

namespace Simplyin\Payment\Api;

use Magento\Quote\Api\Data\CartInterface;

/**
 * Interface IntegratorInterface
 *
 * Defines the contract for shipping module integrators that set pickup point
 * extension attributes on quotes for different shipping providers.
 *
 * @api
 */
interface IntegratorInterface
{
    /**
     * Check if the corresponding shipping module is available and enabled
     *
     * @return bool True if the shipping module is installed and active
     */
    public function isAvailable(): bool;

    /**
     * Set pickup point data on the quote
     *
     * Sets the appropriate extension attributes on the quote based on
     * the shipping module's requirements.
     *
     * @param CartInterface $quote The quote to set pickup point data on
     * @param array $data Pickup point data containing at minimum:
     *                    - lockerId: string - The provider-specific locker/pickup point ID
     *                    - providerName: string - The normalized provider name
     *                    Additional fields may include address, city, postalCode, etc.
     * @return bool True if the pickup point was successfully set
     */
    public function setPickupPoint(CartInterface $quote, array $data): bool;

    /**
     * Get the provider names this integrator handles
     *
     * Returns an array of normalized provider names (lowercase) that this
     * integrator is responsible for handling.
     *
     * @return array List of provider names (e.g., ['inpost'] or ['orlen', 'orlenpaczka'])
     */
    public function getProviderNames(): array;
}
