<?php
/**
 * BookiFlex Onboarding Extension
 *
 * @package    BookiFlex
 * @subpackage Onboarding
 * @author     BookiFlex
 * @copyright  Copyright (c) 2025 BookiFlex
 * @license    GPL-2.0-or-later
 *
 * @link       https://bookiflex.com
 */

declare(strict_types=1);

namespace BookiFlex\Extensions\Onboarding\Contract;

use BookiFlex\Extensions\Onboarding\ValueObject\OnboardingConfiguration;
use BookiFlex\Extensions\Onboarding\ValueObject\OnboardingResult;
use BookiFlex\Core\Service\CptCreator\CptCreatorInterface;
use BookiFlex\Extensions\Onboarding\Service\OnboardingStateManager;

defined( 'ABSPATH' ) || exit;

/**
 * Onboarding Handler Interface
 *
 * Strategy pattern interface for mode-specific onboarding handlers.
 * Implementations: QuickSetupHandler, TestDataHandler, ManualConfigHandler
 *
 * @package BookiFlex\Extensions\Onboarding\Contract
 * @since   1.0.0
 */
interface OnboardingHandlerInterface
{
    /**
     * Handle onboarding for specific mode
     *
     * @param  OnboardingConfiguration $config       Onboarding configuration
     * @param  CptCreatorInterface     $cptCreator   CPT creator service
     * @param  OnboardingStateManager  $stateManager State manager
     * @return OnboardingResult Execution result with next steps
     * @throws \RuntimeException If entity creation fails
     */
    public function handle(
        OnboardingConfiguration $config,
        CptCreatorInterface $cptCreator,
        OnboardingStateManager $stateManager
    ): OnboardingResult;
}
