<?php
/**
 * OpenRouter connector self-registration for the WordPress 7.0 Connectors API.
 *
 * @package AIPT\Core\Connectors
 * @since   2.6.0
 */

declare(strict_types=1);

namespace AIPT\Core\Connectors;

/**
 * Self-registers OpenRouter as a WP 7.0 Connector.
 *
 * ## DORMANT — NOT CURRENTLY HOOKED (since 2.6.x)
 *
 * This class is intentionally NOT wired into `wp_connectors_init` anymore.
 * The registration was removed because the WP Connectors UI mis-detected
 * the locally-stored OpenRouter key as Connectors-managed even when the
 * user had only ever set it through the plugin's own settings page.
 *
 * The class is kept (rather than deleted) so:
 *  - The struct shape regression test (`OpenRouterConnectorRegistrarTest`)
 *    keeps locking the expected Connectors authentication contract.
 *  - Re-enabling is a one-line revert in `Init::init_hooks()`.
 *
 * OpenRouter credentials are now sourced exclusively from the plugin's
 * local AES-256-GCM storage (`aipt_openrouter_api_key`).
 *
 * ## Original (pre-deactivation) wiring
 *
 *     add_action(
 *         'wp_connectors_init',
 *         array( OpenRouterConnectorRegistrar::class, 'register' )
 *     );
 *
 * @since 2.6.0
 */
final class OpenRouterConnectorRegistrar {

	/**
	 * Registers the OpenRouter connector with the WP 7.0 connector registry.
	 *
	 * Originally invoked by the wp_connectors_init action (which was wired in
	 * Init::init_hooks(), not here). The wiring is currently DORMANT — see the
	 * class-level docblock above. Acts as a no-op when 'openrouter' is already
	 * registered so that a third-party plugin taking ownership does not trigger
	 * conflicts.
	 *
	 * @since 2.6.0
	 *
	 * @param \WP_Connector_Registry $registry Connector registry instance.
	 * @return void
	 */
	public static function register( \WP_Connector_Registry $registry ): void {
		if ( $registry->is_registered( 'openrouter' ) ) {
			return;
		}

		$registry->register( 'openrouter', self::getConnectorStruct() );
	}

	/**
	 * Returns the canonical connector struct for OpenRouter.
	 *
	 * Extracted as a public method so test code can introspect the struct shape
	 * independently without invoking the registry.
	 *
	 * Struct shape mirrors the built-in AI provider connectors defined in
	 * wp-includes/connectors.php lines 286–322. The setting_name, constant_name,
	 * and env_var_name fields are provided explicitly here following the naming
	 * pattern that _wp_connectors_register_default_ai_providers() auto-generates
	 * for built-ins (wp-includes/connectors.php lines 384–393):
	 *
	 *   setting_name  → connectors_ai_{id}_api_key
	 *   constant_name → {UPPERCASE_ID}_API_KEY
	 *   env_var_name  → {UPPERCASE_ID}_API_KEY
	 *
	 * @since 2.6.0
	 *
	 * @return array<string, mixed> Connector struct compatible with WP_Connector_Registry::register().
	 */
	public static function getConnectorStruct(): array {
		return array(
			'name'           => 'OpenRouter',
			'description'    => __( 'Multi-model AI aggregator (Claude, GPT, Llama, and more).', 'ai-product-tools' ),
			'type'           => 'ai_provider',
			'logo_url'       => plugins_url( 'src/Assets/images/connectors/openrouter.svg', \AIPT_PLUGIN_FILE ),
			'authentication' => array(
				'method'          => 'api_key',
				'credentials_url' => 'https://openrouter.ai/keys',
				'setting_name'    => 'connectors_ai_openrouter_api_key',
				'constant_name'   => 'OPENROUTER_API_KEY',
				'env_var_name'    => 'OPENROUTER_API_KEY',
			),
			'plugin'         => array(
				'file' => plugin_basename( \AIPT_PLUGIN_FILE ),
			),
		);
	}
}
