<?php
declare(strict_types=1);

namespace Ekesto\CacheInvalidator\Core\WooCommerce;

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

    /**
     * Resolve the canonical permalink for the WooCommerce Shop page.
     *
     * @return string Absolute URL, or empty string when unavailable.
     */
    public function getShopPageUrl(): string;

    /**
     * Resolve canonical baseline targets for a WooCommerce product update.
     *
     * @param \WP_Post $post Triggering post.
     * @return array{post_ids:int[],urls:string[],trusted_urls:string[]}
     */
    public function resolveProductBaseline(\WP_Post $post): array;

    /**
     * Return WooCommerce-specific taxonomy allowlist for archive resolution.
     *
     * Returning null keeps generic archive behavior.
     *
     * @param string $postType Post type slug.
     * @return string[]|null
     */
    public function getAllowedTaxonomiesForPostType(string $postType): ?array;

    /**
     * Resolve the parent product ID for a WooCommerce product variation change.
     *
     * @param int   $variationId Variation post ID.
     * @param mixed $variation   WooCommerce variation object when provided.
     * @return int Parent product ID, or 0 when unavailable.
     */
    public function resolveProductVariationParentId(int $variationId, $variation = null): int;
}
