<?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\OnboardingMode;

defined( 'ABSPATH' ) || exit;

/**
 * Onboarding Presets Provider Interface
 *
 * Provides version-specific preset data for onboarding wizard.
 * Each plugin version (Free/Pro) implements this interface to provide
 * its own set of predefined cancellation policies and payment types.
 *
 * @package BookiFlex\Extensions\Onboarding\Contract
 * @since   1.0.0
 */
interface OnboardingPresetsProviderInterface
{
    /**
     * Get predefined cancellation policies
     *
     * Returns array of cancellation policy templates that will be created
     * during onboarding initialization if none exist in the database.
     *
     * @return array<int, array<string, mixed>> Array of cancellation policy data
     *
     * Example structure:
     * [
     *     [
     *         'title' => 'Flexible (24h)',
     *         'excerpt' => 'Free cancellation 24h before check-in',
     *         'status' => 'publish',
     *         'predefined_rule' => 'bflex__cp__rule_flexible',
     *     ],
     *     // ... more policies
     * ]
     */
    public function getCancellationPolicies(): array;

    /**
     * Get predefined payment types
     *
     * Returns array of payment type templates that will be created
     * during onboarding initialization if none exist in the database.
     *
     * @return array<int, array<string, mixed>> Array of payment type data
     *
     * Example structure:
     * [
     *     [
     *         'title' => 'Cash',
     *         'excerpt' => 'Payment in cash on arrival',
     *         'status' => 'publish',
     *         'calculator_type' => 'cash',
     *         'payment_payable' => true,
     *         // ... more fields
     *     ],
     *     // ... more payment types
     * ]
     */
    public function getPaymentTypes(): array;

    /**
     * Get next steps for specific onboarding mode
     *
     * Returns array of next step recommendations that will be shown
     * after completing onboarding in the specified mode.
     *
     * @param  OnboardingMode $mode Onboarding mode (quick_setup, test_data, manual)
     * @return array<int, array<string, string>> Array of next step data
     *
     * Example structure:
     * [
     *     [
     *         'title' => 'Add photos',
     *         'description' => 'Upload photos of your accommodation types',
     *         'icon' => '📸',
     *     ],
     *     // ... more steps
     * ]
     */
    public function getNextStepsForMode(OnboardingMode $mode): array;

    /**
     * Get descriptions for accommodation unit type
     *
     * Returns array of description templates (200-300 characters) for the given
     * accommodation unit type. Used for auto-populating accommodation descriptions.
     *
     * @param  string $unitType Unit type (room, bed, unit, etc.)
     * @return string[] Array of description strings (2-3 variations per type)
     *
     * Example: getDescriptionsByUnitType('room') returns:
     * [
     *     'Comfortable room with modern amenities...',
     *     'Cozy room perfect for relaxation...',
     * ]
     */
    public function getDescriptionsByUnitType(string $unitType): array;

    /**
     * Get amenities for accommodation unit type
     *
     * Returns array of typical amenities for the given accommodation unit type.
     * Used for auto-populating accommodation amenities.
     *
     * @param  string $unitType Unit type (room, bed, unit, etc.)
     * @return string[] Array of amenity names (~7 items)
     *
     * Example: getAmenitiesByUnitType('room') returns:
     * ['WiFi', 'TV', 'Air Conditioning', 'Mini Bar', 'Safe', 'Telephone', 'Desk']
     */
    public function getAmenitiesByUnitType(string $unitType): array;

    /**
     * Get descriptions for rate plan board type
     *
     * Returns array of description templates for the given board type.
     * Used for auto-populating rate plan descriptions.
     *
     * @param  string $boardType Board type (ROOM_ONLY, BREAKFAST, HALF_BOARD, etc.)
     * @return string[] Array of description strings (2-3 variations per type)
     *
     * Example: getDescriptionsByBoardType('ROOM_ONLY') returns:
     * [
     *     'Basic rate with room accommodation only...',
     *     'Standard rate without meals included...',
     * ]
     */
    public function getDescriptionsByBoardType(string $boardType): array;

    /**
     * Get test data configuration in unified format
     *
     * Returns unified configuration for creating test accommodation types and rate plans.
     * Used by TestDataHandler to populate the system with sample data.
     *
     * Unified format separates accommodations (physical units) from rate plans (pricing).
     * Accommodations have NO pricing, rate plans contain pricing for accommodations.
     *
     * @return array{accommodationTypes: array<int, array<string, mixed>>, ratePlans: array<int, array<string, mixed>>, currency: string}
     *
     * Example structure:
     * [
     *     'currency' => 'USD',
     *     'accommodationTypes' => [
     *         [
     *             'name' => 'Standard Room',
     *             'mainPlaces' => 2,
     *             'unitType' => 'room',
     *             'availableUnits' => 5,
     *             'description' => 'Comfortable room...',  // optional
     *             'amenities' => ['WiFi', 'TV', ...],      // optional
     *         ],
     *         // ... more accommodation types
     *     ],
     *     'ratePlans' => [
     *         [
     *             'title' => 'Base Rate Plan',
     *             'shortCode' => 'BASE',
     *             'boardType' => BoardType::ROOM_ONLY,
     *             'accommodationIndices' => [0, 1, 2], // indices of accommodations
     *             'weeklyPricing' => [
     *                 0 => [  // pricing for accommodation at index 0
     *                     'mon' => 8000,  // simple format (same price for all variants)
     *                     'tue' => ['__1' => 7000, '__2' => 8000], // occupancy-based
     *                     // ... other days
     *                 ],
     *                 // ... pricing for other accommodations
     *             ],
     *         ],
     *         // ... more rate plans
     *     ],
     * ]
     */
    public function getTestDataConfiguration(): array;

    /**
     * Get booking presets (combined cancellation policy + payment type)
     *
     * Returns array of booking preset templates that combine a cancellation policy
     * and a payment type into a user-friendly preset card for the onboarding wizard.
     *
     * @return array<int, array<string, mixed>> Array of booking preset data
     *
     * Example structure:
     * [
     *     [
     *         'id' => 'flexible_pay_on_arrival',
     *         'cancellationPolicyKey' => 'fully_flexible',
     *         'paymentTypeKey' => 'pay_on_arrival',
     *         'title' => 'Flexible – Pay on Arrival',
     *         'shortDescription' => 'Guests can cancel anytime...',
     *         'recommendation' => 'Best for new hosts...',
     *         'popular' => false,
     *     ],
     *     // ... more presets
     * ]
     */
    public function getBookingPresets(): array;

    /**
     * Get available accommodation types
     *
     * Returns array of accommodation type options available for selection.
     * Used by frontend to display accommodation type options in UI.
     *
     * @return array<int, array{value: string, label: string}> Array of accommodation type options
     *
     * Example structure:
     * [
     *     ['value' => 'room', 'label' => 'Room'],
     *     ['value' => 'bed', 'label' => 'Bed'],
     *     ['value' => 'unit', 'label' => 'Rental unit'],
     * ]
     */
    public function getAccommodationTypes(): array;
}
