<?php
/**
 * Checks the Connector Hub this site actually talks to, not a checkout of it.
 *
 * The repo-side contract tests (tests/oauth-action-contract.php, mirrored in
 * ai-o-connector-hub) compare two source trees. They cannot see which build is
 * deployed at the Hub, and a stale deployment is precisely what broke Search
 * Console, GA4 and Business Profile OAuth together: Hub 1.6.2 did not
 * recognise this plugin's renamed return actions, so it never stamped a
 * purpose and every OAuth attempt was rejected. Nothing surfaced that until a
 * connection failed with a message that did not name the cause. See
 * CONNECTOR-HUB-1.6.3-COMPATIBILITY.md.
 *
 * So: ask the Hub which return actions it recognises, compare against the ones
 * this plugin will actually send, and say so plainly while it can still be
 * fixed. Capabilities rather than a version number — a version means nothing
 * without a list of which versions are good, and that list would drift exactly
 * as the map did.
 *
 * Weight: this plugin runs on every client site. The check is admin-only,
 * cached for a day, skipped entirely unless the site is registered with a Hub,
 * and never blocks a page load to make a request.
 *
 * @package AI_O_Optimiser
 */

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

final class AI_O_Optimiser_Hub_Compatibility {

	const TRANSIENT = 'ai_o_optimiser_hub_compatibility';
	const TTL       = DAY_IN_SECONDS;

	/** Return actions this plugin registers, so the Hub must recognise them. */
	const REQUIRED_ACTIONS = array(
		'ai_o_optimiser_gsc_oauth_return',
		'ai_o_optimiser_ga4_data_oauth_return',
		'ai_o_optimiser_local_gbp_oauth_return',
	);

	/**
	 * Compatibility of the Hub this site is registered with.
	 *
	 * Never makes a request on its own; reads what the last refresh stored.
	 *
	 * @return array{state:string,message:string,missing:string[],hub_version:string}|null
	 *         Null when the site has no Hub connection to judge.
	 */
	public static function status() {
		$cached = get_transient( self::TRANSIENT );
		return is_array( $cached ) ? $cached : null;
	}

	/**
	 * Ask the Hub what it supports and store the verdict.
	 *
	 * @param bool $force Refresh even when a cached verdict is still fresh.
	 * @return array|null Verdict, or null when there is no connection to check.
	 */
	public static function refresh( $force = false ) {
		if ( ! $force ) {
			$cached = get_transient( self::TRANSIENT );
			if ( is_array( $cached ) ) {
				return $cached;
			}
		}

		if ( ! class_exists( 'AI_O_Optimiser_Connector_Client' ) ) {
			return null;
		}

		$settings = AI_O_Optimiser_Connector_Client::settings();
		if ( empty( $settings['connector_id'] ) || empty( $settings['connector_secret'] ) ) {
			// Not registered with a Hub, so there is nothing to be incompatible with.
			return null;
		}

		$response = AI_O_Optimiser_Connector_Client::hub_request( '/status', array() );
		if ( is_wp_error( $response ) ) {
			// A request that failed says nothing about compatibility. Do not
			// cache a verdict from it; the connection screens report transport
			// errors already.
			return null;
		}

		$verdict = self::judge( $response );
		set_transient( self::TRANSIENT, $verdict, self::TTL );
		return $verdict;
	}

	/**
	 * Decide what a /status response means for this plugin's OAuth flows.
	 *
	 * @param array $response Decoded /status response.
	 * @return array{state:string,message:string,missing:string[],hub_version:string}
	 */
	public static function judge( $response ) {
		$response    = is_array( $response ) ? $response : array();
		$hub_version = isset( $response['hub_version'] ) ? sanitize_text_field( (string) $response['hub_version'] ) : '';

		if ( ! isset( $response['oauth_actions'] ) || ! is_array( $response['oauth_actions'] ) ) {
			/*
			 * A Hub too old to declare its capabilities. This is the shape the
			 * broken 1.6.2 build had, but older compatible builds look the same,
			 * so this is reported as unknown rather than broken. Saying "your Hub
			 * cannot tell us" is honest and still points at the right place;
			 * claiming it is broken would cry wolf on working sites.
			 */
			return array(
				'state'       => 'unknown',
				'message'     => __( 'This Connector Hub is too old to report which Google sign-in returns it accepts, so compatibility cannot be confirmed. If connecting Search Console, Analytics or Business Profile fails, an out-of-date Hub is the first thing to check.', 'ai-o-optimiser' ),
				'missing'     => array(),
				'hub_version' => $hub_version,
			);
		}

		$supported = array_map( 'strval', $response['oauth_actions'] );
		$missing   = array_values( array_diff( self::REQUIRED_ACTIONS, $supported ) );

		if ( empty( $missing ) ) {
			return array(
				'state'       => 'ok',
				'message'     => __( 'The Connector Hub recognises this plugin\'s Google sign-in returns.', 'ai-o-optimiser' ),
				'missing'     => array(),
				'hub_version' => $hub_version,
			);
		}

		return array(
			'state'       => 'incompatible',
			'message'     => sprintf(
				/* translators: 1: comma-separated Google service names, 2: Hub version or "unknown". */
				__( 'The Connector Hub does not accept this plugin\'s sign-in returns for %1$s, so connecting those services will fail until the Hub is updated. Hub version reported: %2$s.', 'ai-o-optimiser' ),
				implode( ', ', self::service_names( $missing ) ),
				'' !== $hub_version ? $hub_version : __( 'unknown', 'ai-o-optimiser' )
			),
			'missing'     => $missing,
			'hub_version' => $hub_version,
		);
	}

	/**
	 * Name the affected services the way an administrator would recognise them.
	 *
	 * "ai_o_optimiser_local_gbp_oauth_return is missing" is true and useless to
	 * the person who has to act on it.
	 *
	 * @param string[] $actions Missing action names.
	 * @return string[]
	 */
	private static function service_names( $actions ) {
		$names = array(
			'ai_o_optimiser_gsc_oauth_return'       => __( 'Search Console', 'ai-o-optimiser' ),
			'ai_o_optimiser_ga4_data_oauth_return'  => __( 'Google Analytics', 'ai-o-optimiser' ),
			'ai_o_optimiser_local_gbp_oauth_return' => __( 'Google Business Profile', 'ai-o-optimiser' ),
		);
		$out = array();
		foreach ( $actions as $action ) {
			$out[] = isset( $names[ $action ] ) ? $names[ $action ] : $action;
		}
		return $out;
	}

	/** Drop the cached verdict, so the next refresh asks again. */
	public static function flush() {
		delete_transient( self::TRANSIENT );
	}
}