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

namespace Hafenstudios\Kurato\Cockpit;

defined( 'ABSPATH' ) || exit;

/**
 * Seam fuer die Schattennutzer-Verwaltung. Trennt die reine agents/sync-Logik
 * (AgentSync) von den WordPress-Nutzerfunktionen, damit die Idempotenz ohne
 * WordPress testbar bleibt. Produktion: WpShadowUserStore.
 */
interface ShadowUserStore {

	/**
	 * Findet den WP-Nutzer zu einer Agent-ID.
	 *
	 * @param string $agent_id Agent-ID des Dienstes.
	 * @return int|null WP-Nutzer-ID oder null.
	 */
	public function find_by_agent( string $agent_id ): ?int;

	/**
	 * Legt einen Schattennutzer an (Rolle kurato_agent, zufaelliges Passwort).
	 *
	 * @param string $agent_id Agent-ID.
	 * @param string $email    E-Mail.
	 * @param string $name     Anzeigename.
	 * @return int WP-Nutzer-ID (0 bei Fehler).
	 */
	public function create( string $agent_id, string $email, string $name ): int;

	/**
	 * Aktualisiert E-Mail und Anzeigename eines Schattennutzers.
	 *
	 * @param int    $wp_user_id WP-Nutzer-ID.
	 * @param string $email      E-Mail.
	 * @param string $name       Anzeigename.
	 * @return void
	 */
	public function update( int $wp_user_id, string $email, string $name ): void;

	/**
	 * Aktiviert bzw. deaktiviert einen Schattennutzer.
	 *
	 * @param int  $wp_user_id WP-Nutzer-ID.
	 * @param bool $active     Aktiv?
	 * @return void
	 */
	public function set_active( int $wp_user_id, bool $active ): void;

	/**
	 * Entrechtet ALLE Schattennutzer (Trennen der Kopplung, CP1-9): Sperr-Meta
	 * setzen und die Rolle kurato_agent entziehen. Die Nutzer bleiben fuer die
	 * Historien-Attribution bestehen; ohne Rolle haben sie keinerlei
	 * Capabilities, auch nicht nach einem Passwort-Reset.
	 *
	 * @return void
	 */
	public function deactivate_all(): void;
}
