<?php
/**
 * Social Login Provider Interface.
 *
 * Contract for all OAuth social login providers.
 * Each provider wraps a league/oauth2-client provider
 * and normalizes the user data to a common format.
 *
 * @package GuardDog
 * @since 1.9.30
 */

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

/**
 * Interface Guard_Dog_Social_Provider_Interface
 *
 * Defines the contract that all social login providers must implement.
 * Providers are responsible for creating the underlying League OAuth2
 * provider, defining their scopes, and normalizing the resource owner
 * data into a consistent array format.
 *
 * @since 1.9.30
 */
interface Guard_Dog_Social_Provider_Interface {

    /**
     * Get the unique provider identifier.
     *
     * Used as the key in provider registries and database records.
     * Must be a lowercase alphanumeric string (e.g., 'google', 'github').
     *
     * @since 1.9.30
     * @return string Provider identifier.
     */
    public function get_id(): string;

    /**
     * Get the human-readable provider name.
     *
     * Used in the admin UI and login form buttons.
     * Should be translatable via __() or esc_html__().
     *
     * @since 1.9.30
     * @return string Translated provider display name.
     */
    public function get_name(): string;

    /**
     * Get the provider's brand icon as an inline SVG string.
     *
     * Used in the login form buttons. Should be a complete <svg> element
     * with appropriate viewBox and dimensions for inline rendering.
     *
     * @since 1.9.30
     * @return string SVG markup for the provider's brand icon.
     */
    public function get_icon_svg(): string;

    /**
     * Get the provider's primary brand color.
     *
     * Used for styling login buttons. Should be a valid CSS color value
     * (hex, rgb, etc.).
     *
     * @since 1.9.30
     * @return string CSS color value (e.g., '#4285F4').
     */
    public function get_color(): string;

    /**
     * Get the OAuth scopes required by this provider.
     *
     * Returns the list of OAuth2 scopes needed to retrieve
     * the user's identity information (email, name, avatar).
     *
     * @since 1.9.30
     * @return array List of OAuth scope strings.
     */
    public function get_scopes(): array;

    /**
     * Create the underlying League OAuth2 provider instance.
     *
     * Accepts a configuration array with provider-specific credentials
     * and returns a configured League AbstractProvider instance.
     *
     * @since 1.9.30
     *
     * @param array $config {
     *     Provider configuration.
     *
     *     @type string $client_id     OAuth client ID.
     *     @type string $client_secret OAuth client secret.
     *     @type string $redirect_uri  OAuth callback URL.
     * }
     * @return \GuardDog\Vendor\League\OAuth2\Client\Provider\AbstractProvider Configured provider instance.
     */
    public function create_league_provider( array $config ): \GuardDog\Vendor\League\OAuth2\Client\Provider\AbstractProvider;

    /**
     * Normalize the resource owner data into a common format.
     *
     * Converts the provider-specific ResourceOwnerInterface into
     * a standard associative array with consistent keys.
     *
     * @since 1.9.30
     *
     * @param \GuardDog\Vendor\League\OAuth2\Client\Provider\ResourceOwnerInterface $resource_owner The authenticated resource owner.
     * @return array {
     *     Normalized user data.
     *
     *     @type string      $provider_user_id Provider-specific user ID.
     *     @type string      $email            User's email address.
     *     @type string      $name             User's full/display name.
     *     @type string|null $first_name       User's first name, if available.
     *     @type string|null $last_name        User's last name, if available.
     *     @type string|null $avatar_url       URL to user's profile picture, if available.
     * }
     */
    public function normalize_resource_owner( \GuardDog\Vendor\League\OAuth2\Client\Provider\ResourceOwnerInterface $resource_owner ): array;

    /**
     * Get the settings fields required to configure this provider.
     *
     * Returns an array of field definitions used in the admin settings UI.
     * Each field definition describes the input needed from the site admin.
     *
     * @since 1.9.30
     *
     * @return array List of field definitions, each containing:
     *               - 'id'          (string) Field identifier.
     *               - 'label'       (string) Human-readable field label.
     *               - 'type'        (string) Input type ('text', 'password', etc.).
     *               - 'required'    (bool)   Whether the field is required.
     *               - 'description' (string) Help text for the field.
     */
    public function get_settings_fields(): array;

    /**
     * Check if this provider has all required configuration.
     *
     * Each provider defines what configuration it needs. For example,
     * Google/Microsoft need client_id + client_secret, while Apple
     * needs client_id + team_id + key_id + key_file.
     *
     * @since 1.9.30
     * @return bool True if the provider has all required options configured.
     */
    public function is_configured(): bool;
}
