<?php

declare(strict_types=1);

namespace AIPT\Utils\Credentials;

/**
 * Contract for credential providers.
 *
 * Implementations resolve API credentials from various sources (environment variables,
 * PHP constants, WordPress Connectors database, or local plugin storage). Providers
 * MUST NOT throw on missing credentials—return null and NONE source instead. Throw
 * only on programming errors (unknown $aiptProvider).
 *
 * @since 2.6.0
 */
interface CredentialProviderInterface {

	/**
	 * Resolves an API key for the given AIPT provider.
	 *
	 * Returns the plaintext key if configured, or null if not found. Implementations
	 * MUST NOT throw on missing credentials; throw only on programming errors.
	 *
	 * @since 2.6.0
	 *
	 * @param string $aiptProvider One of 'openai', 'gemini', 'claude', 'openrouter'.
	 * @return string|null The resolved API key, or null if not configured.
	 *
	 * @throws \InvalidArgumentException If $aiptProvider is not recognized.
	 */
	public function getKey( string $aiptProvider ): ?string;

	/**
	 * Returns the source of the credential for the given provider.
	 *
	 * Indicates where the credential came from (environment variable, PHP constant,
	 * Connectors database, local storage, or not configured).
	 *
	 * @since 2.6.0
	 *
	 * @param string $aiptProvider One of 'openai', 'gemini', 'claude', 'openrouter'.
	 * @return string One of CredentialSource constants.
	 *
	 * @throws \InvalidArgumentException If $aiptProvider is not recognized.
	 */
	public function getSource( string $aiptProvider ): string;

	/**
	 * Checks if a credential is configured for the given provider.
	 *
	 * Convenience method: returns true iff getKey() would return a non-empty string.
	 *
	 * @since 2.6.0
	 *
	 * @param string $aiptProvider One of 'openai', 'gemini', 'claude', 'openrouter'.
	 * @return bool True if credential is configured, false otherwise.
	 *
	 * @throws \InvalidArgumentException If $aiptProvider is not recognized.
	 */
	public function isConfigured( string $aiptProvider ): bool;

	/**
	 * Returns the human-readable label for the credential source.
	 *
	 * Convenience method: returns CredentialSource::label( $this->getSource( $aiptProvider ) ).
	 * Implementations MAY override for richer, context-aware labels.
	 *
	 * @since 2.6.0
	 *
	 * @param string $aiptProvider One of 'openai', 'gemini', 'claude', 'openrouter'.
	 * @return string Translated label suitable for display.
	 *
	 * @throws \InvalidArgumentException If $aiptProvider is not recognized.
	 */
	public function getSourceLabel( string $aiptProvider ): string;
}
