<?php
/**
 * Auth Provider Interface
 *
 * Contract for authentication services. Enables alternative auth
 * implementations without changing consumer code.
 *
 * @package Niwa_AI
 * @since   0.10.36
 */

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

interface Niwa_AI_Auth_Provider_Interface {

	/**
	 * Get current authentication mode.
	 *
	 * @return string 'api_key' or 'oauth'.
	 */
	public function get_mode();

	/**
	 * Get credentials for the current auth mode.
	 *
	 * @return array For 'oauth': {access_token, refresh_token, account_id}.
	 *               For 'api_key': {api_key}.
	 */
	public function get_credentials();

	/**
	 * Get API key specifically.
	 *
	 * @return string API key or empty string if not configured.
	 */
	public function get_api_key();

	/**
	 * Get comprehensive OAuth status.
	 *
	 * @return array { connected: bool, expired: bool, expiring_soon: bool, email: string, ... }
	 */
	public function get_oauth_status();

	/**
	 * Clear all OAuth tokens and reset to API key mode.
	 *
	 * @return void
	 */
	public function clear_oauth_credentials();

	/**
	 * Persist an OAuth error message so it is visible in the admin panel.
	 *
	 * @param string $message Error message.
	 * @return void
	 */
	public function set_oauth_last_error( $message );

	/**
	 * Start OAuth device authorization flow.
	 *
	 * @param int $user_id WordPress user ID.
	 * @return array { success: bool, session?: array, verification_url?: string, error?: string }
	 */
	public function start_codex_device_flow( $user_id );

	/**
	 * Poll OAuth device flow for completion.
	 *
	 * @param int $user_id WordPress user ID.
	 * @return array { success: bool, pending?: bool, retry_after?: int, tokens?: array, error?: string }
	 */
	public function poll_codex_device_flow( $user_id );

	/**
	 * Get current device OAuth session status.
	 *
	 * @param int $user_id WordPress user ID.
	 * @return array { active: bool, user_code?: string, interval?: int, ... }
	 */
	public function get_codex_device_status( $user_id );

	/**
	 * Complete OAuth authorization code flow.
	 *
	 * @param array $args { code: string, state: string, redirect_uri: string, user_id: int }
	 * @return array { success: bool, tokens?: array, error?: string }
	 */
	public function complete_codex_oauth( $args );
}
