<?php
/**
 * @package Hafenstudios\Leadlotse
 */

namespace Hafenstudios\Leadlotse\Identity;

defined( 'ABSPATH' ) || exit;

/**
 * Gemeinsame Schnittstelle der Identity-Anbieter (Google, Apple, spaeter mehr).
 *
 * Ein Anbieter ist zustandslos: er baut die Weiterleitungs-URL zum Anbieter und
 * tauscht den zurueckkommenden Code gegen die verifizierte E-Mail (und, wenn
 * verfuegbar, den Namen) ein. KEIN WordPress-Login, KEINE Nutzerkonten - die
 * Angaben dienen nur dazu, das oeffentliche Lead-Formular vorzubefuellen.
 */
interface ProviderInterface {

	/**
	 * Stabiler Schluessel des Anbieters (z.B. "google", "apple").
	 *
	 * @return string
	 */
	public function key(): string;

	/**
	 * Anzeigename fuer Knoepfe und Hinweise (z.B. "Google").
	 *
	 * @return string
	 */
	public function label(): string;

	/**
	 * Sind alle noetigen Zugangsdaten hinterlegt?
	 *
	 * @return bool
	 */
	public function is_configured(): bool;

	/**
	 * Baut die Weiterleitungs-URL zum Anbieter.
	 *
	 * @param string $state        Signierter State-Parameter (CSRF-Schutz).
	 * @param string $redirect_uri Ruecksprung-URL (unser Callback-Endpoint).
	 * @return string
	 */
	public function authorize_url( string $state, string $redirect_uri ): string;

	/**
	 * Tauscht den Autorisierungscode gegen die verifizierte E-Mail ein.
	 *
	 * @param string               $code         Autorisierungscode des Anbieters.
	 * @param string               $redirect_uri Dieselbe Ruecksprung-URL wie bei authorize_url.
	 * @param array<string, mixed> $extra        Zusaetzliche Callback-Parameter (z.B. Apple 'user').
	 * @return array{email:string,email_verified:bool,name:string}|\WP_Error
	 */
	public function exchange( string $code, string $redirect_uri, array $extra = array() );
}
