<?php
/**
 * SEO provider integration contract.
 *
 * @package SmartyPress_AI_Engine
 * @since 1.0.0
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Base class for integrations with third-party SEO plugins.
 */
abstract class SmartyPress_AI_SEO_Provider_Integration {

	/**
	 * Get provider identifier used by REST and JS.
	 *
	 * @return string
	 */
	abstract public function get_id();

	/**
	 * Get provider label for UI.
	 *
	 * @return string
	 */
	abstract public function get_label();

	/**
	 * Check whether the SEO plugin is available.
	 *
	 * @return bool
	 */
	abstract public function is_available();

	/**
	 * Check whether the provider supports the current post type.
	 *
	 * @param string $post_type Post type name.
	 * @return bool
	 */
	public function supports_post_type( $post_type ) {
		return in_array( $post_type, array( 'post', 'page' ), true );
	}

	/**
	 * Get normalized SEO context for an editor.
	 *
	 * @param int $post_id Post ID.
	 * @return array
	 */
	abstract public function get_editor_context( $post_id );

	/**
	 * Get supported test groups.
	 *
	 * @return array
	 */
	abstract public function get_supported_tests();

	/**
	 * Normalize provider-specific failed tests.
	 *
	 * @param array $raw_tests Raw failed tests.
	 * @return array
	 */
	abstract public function normalize_failed_tests( $raw_tests );

	/**
	 * Apply SEO metadata changes on the server side.
	 *
	 * Gutenberg applies most changes in the editor first, but this method keeps
	 * the provider contract useful for future Classic Editor and bulk flows.
	 *
	 * @param int   $post_id Post ID.
	 * @param array $changes Normalized changes.
	 * @return array Result data.
	 */
	abstract public function apply_metadata_changes( $post_id, $changes );

	/**
	 * Normalize a comma-separated keyword string.
	 *
	 * @param string|array $keywords Keywords.
	 * @return array
	 */
	protected function normalize_keywords( $keywords ) {
		if ( is_array( $keywords ) ) {
			$items = $keywords;
		} else {
			$items = explode( ',', (string) $keywords );
		}

		$items = array_map( 'trim', $items );
		$items = array_filter( $items );

		return array_values( array_unique( $items ) );
	}
}
