<?php
/**
 * SimplyIN Payment Module
 *
 * Interface for the central pickup point processor that coordinates
 * all shipping module integrators.
 */
declare(strict_types=1);

namespace Simplyin\Payment\Api;

use Magento\Quote\Api\Data\CartInterface;

/**
 * Interface PickupPointProcessorInterface
 *
 * Defines the contract for the central processor that coordinates pickup point
 * data processing across different shipping module integrators. This processor
 * routes pickup point data to the appropriate integrator based on provider name.
 *
 * @api
 */
interface PickupPointProcessorInterface
{
    /**
     * Process pickup point data and set extension attributes
     *
     * Routes the pickup point data to the appropriate integrator based on
     * the provider name and sets the required extension attributes on the quote.
     * Handles unknown providers gracefully by logging a warning and returning false.
     *
     * @param CartInterface $quote The quote to set pickup point data on
     * @param array $pickupPointData Pickup point data containing at minimum:
     *                               - lockerId: string - The provider-specific locker/pickup point ID
     *                               - providerName: string - The provider name (will be normalized)
     *                               Additional fields may include address, city, postalCode, etc.
     * @return bool True if the pickup point was successfully processed, false otherwise
     */
    public function process(CartInterface $quote, array $pickupPointData): bool;

    /**
     * Get supported provider names
     *
     * Returns an array of all provider names supported by the registered integrators.
     * Provider names are normalized to lowercase.
     *
     * @return array List of supported provider names (e.g., ['inpost', 'orlen', 'orlenpaczka', 'dpd'])
     */
    public function getSupportedProviders(): array;
}
