<?php

declare(strict_types=1);

namespace AIPT\Utils\Credentials;

/**
 * Value object enumerating credential source types with i18n-aware human labels.
 *
 * Represents where an API credential originates: environment variables, PHP constants,
 * WordPress Connectors database, or local plugin storage. Used by credential providers
 * to indicate the source of resolved credentials.
 *
 * @since 2.6.0
 */
final class CredentialSource {

	/**
	 * Credential sourced from environment variable (Connectors-managed).
	 *
	 * @since 2.6.0
	 */
	public const ENV = 'env';

	/**
	 * Credential sourced from PHP constant (Connectors-managed).
	 *
	 * @since 2.6.0
	 */
	public const CONSTANT = 'constant';

	/**
	 * Credential sourced from WordPress Connectors database.
	 *
	 * @since 2.6.0
	 */
	public const DATABASE_CONNECTORS = 'database_connectors';

	/**
	 * Credential sourced from local plugin database storage (Connectors fallback).
	 *
	 * @since 2.6.0
	 */
	public const DATABASE_LOCAL = 'database_local';

	/**
	 * No credential configured.
	 *
	 * @since 2.6.0
	 */
	public const NONE = 'none';

	/**
	 * Returns all valid credential source constants.
	 *
	 * @since 2.6.0
	 *
	 * @return array<int, string> Array of source constants.
	 */
	public static function all(): array {
		return array(
			self::ENV,
			self::CONSTANT,
			self::DATABASE_CONNECTORS,
			self::DATABASE_LOCAL,
			self::NONE,
		);
	}

	/**
	 * Checks if a source string is valid.
	 *
	 * @since 2.6.0
	 *
	 * @param string $source The source to validate.
	 * @return bool True if source is in self::all(), false otherwise.
	 */
	public static function isValid( string $source ): bool {
		return in_array( $source, self::all(), true );
	}

	/**
	 * Returns human-readable label for a credential source.
	 *
	 * @since 2.6.0
	 *
	 * @param string $source One of the CredentialSource constants.
	 * @return string Translated label suitable for display.
	 *
	 * @throws \InvalidArgumentException If source is not recognized.
	 */
	public static function label( string $source ): string {
		switch ( $source ) {
			case self::ENV:
				return __( 'Environment variable', 'ai-product-tools' );
			case self::CONSTANT:
				return __( 'PHP constant', 'ai-product-tools' );
			case self::DATABASE_CONNECTORS:
				return __( 'WordPress Connectors', 'ai-product-tools' );
			case self::DATABASE_LOCAL:
				return __( 'Local plugin key', 'ai-product-tools' );
			case self::NONE:
				return __( 'Not configured', 'ai-product-tools' );
			default:

				throw new \InvalidArgumentException( "Unknown credential source: {$source}" );
		}
	}

	/**
	 * Returns short badge text for a credential source.
	 *
	 * Suitable for UI badges indicating credential management status.
	 *
	 * @since 2.6.0
	 *
	 * @param string $source One of the CredentialSource constants.
	 * @return string Translated badge text.
	 *
	 * @throws \InvalidArgumentException If source is not recognized.
	 */
	public static function badgeText( string $source ): string {
		switch ( $source ) {
			case self::ENV:
				return __( 'Managed by Connectors (env var)', 'ai-product-tools' );
			case self::CONSTANT:
				return __( 'Managed by Connectors (constant)', 'ai-product-tools' );
			case self::DATABASE_CONNECTORS:
				return __( 'Managed by Connectors (database)', 'ai-product-tools' );
			case self::DATABASE_LOCAL:
				return __( 'Local key (Connectors fallback)', 'ai-product-tools' );
			case self::NONE:
				return __( 'Not configured', 'ai-product-tools' );
			default:

				throw new \InvalidArgumentException( "Unknown credential source: {$source}" );
		}
	}
}
