<?php
declare(strict_types=1);

namespace Ekesto\CacheInvalidator\Core\Elementor;

use Ekesto\CacheInvalidator\Integrations\Structural\Providers\Contracts\StructuralContainerProviderInterface;

/**
 * Lite-safe Elementor integration seam for shared invalidation code.
 */
interface ElementorIntegrationInterface
{
    /**
     * Determine whether a concrete Elementor integration provider is active.
     *
     * @return bool True when Elementor implementation services are available.
     */
    public function isAvailable(): bool;

    /**
     * Classify one Elementor library post ID.
     *
     * @param int $postId Elementor library post ID.
     * @return string One ElementorDocumentClassification::* value.
     */
    public function classifyLibraryPost(int $postId): string;

    /**
     * Return Elementor structural providers.
     *
     * @return StructuralContainerProviderInterface[]
     */
    public function structuralProviders(): array;

    /**
     * Resolve stored Elementor conditions for one template.
     *
     * @param int $postId Elementor library post ID.
     * @return array{post_ids:int[],urls:string[],certain:bool,resolution:string,fallback_reason:string}
     */
    public function resolveElementorConditions(int $postId): array;

    /**
     * Resolve an explicit effective Elementor condition set for one template.
     *
     * @param int              $postId Elementor library post ID.
     * @param array<int,mixed> $conditions Effective condition strings.
     * @return array{post_ids:int[],urls:string[],certain:bool,resolution:string,fallback_reason:string}
     */
    public function resolveEffectiveConditions(int $postId, array $conditions): array;
}
