<?php
/**
 * Extensions (spec §3.3) this store advertises, and those an agent supports.
 *
 * Extensions defined by the protocol have plain names (`operations`). Ours
 * MUST start with a domain we control (spec 3.3). AGENTADAPT_EXTENSION_DOMAIN
 * is that domain.
 *
 * getagentadapt.com was registered to us at Cloudflare on 11 Oct 2026
 * (PLAN.md D1). Changing it renames every extension we advertise, so treat
 * it as part of the protocol surface.
 *
 * @package AgentAdapt
 */

defined( 'ABSPATH' ) || exit;

if ( ! defined( 'AGENTADAPT_EXTENSION_DOMAIN' ) ) {
	define( 'AGENTADAPT_EXTENSION_DOMAIN', 'getagentadapt.com' );
}

/**
 * Extension registry.
 */
final class AgentAdapt_Extensions {

	/**
	 * Fully qualified name for one of our extensions.
	 *
	 * @param string $short e.g. 'checkout-handoff'.
	 */
	public static function name( string $short ): string {
		return AGENTADAPT_EXTENSION_DOMAIN . '/' . $short;
	}

	/**
	 * Extensions the store advertises in poppy.json, keyed by name.
	 *
	 * @return array<string, array<string,mixed>>
	 */
	public static function advertised(): array {
		/**
		 * Advertised extensions. Each entry needs at least a `version`.
		 *
		 * @param array<string, array<string,mixed>> $extensions Name → settings.
		 */
		return (array) apply_filters( 'agentadapt_extensions', array() );
	}

	/**
	 * Whether an agent's client metadata lists an extension at a major
	 * version we implement.
	 *
	 * @param array<string,mixed> $agent_meta Client metadata document.
	 * @param string              $name       Extension name.
	 * @param string              $version    Major version.
	 */
	public static function agent_supports( array $agent_meta, string $name, string $version ): bool {
		$ext = $agent_meta['extensions'][ $name ] ?? null;
		return is_array( $ext ) && (string) ( $ext['version'] ?? '' ) === $version;
	}
}