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

declare(strict_types=1);

namespace BookiFlex\Core\Service\CptCreator;

defined( 'ABSPATH' ) || exit;

/**
 * Service for programmatic creation of Custom Post Types.
 *
 * Useful for seeds, tests, onboarding, and data imports.
 */
interface CptCreatorInterface
{
    /**
     * Create an AccommodationType CPT.
     *
     * @param array{
     *     title: string,
     *     excerpt?: string,
     *     status?: string,
     *     short_code: string,
     *     living_space?: string,
     *     accommodation_category: string,
     *     accommodation_available_units: int,
     *     key_amenities?: string,
     *     main_sleeping_capacity: int,
     *     main_sleeping_allowed_occupancy: array<int>,
     *     additional_sleeping_places?: int,
     *     enable_extra_occupancy?: bool,
     *     gallery?: array<int>,
     *     thumbnail_id?: int,
     *     address?: string,
     *     phone?: string,
     *     email?: string,
     *     longitude?: string,
     *     latitude?: string,
     *     menu_order?: int
     * } $data AccommodationType data
     * @return int Post ID on success
     * @throws \RuntimeException If creation fails
     */
    public function createAccommodationType(array $data): int;

    /**
     * Create a RatePlan CPT.
     *
     * @param array{
     *     title: string,
     *     excerpt?: string,
     *     status?: string,
     *     board_type: string,
     *     short_code: string,
     *     accommodation_types: array<int>,
     *     payment_types: array<int>,
     *     cancellation_policy: int,
     *     parent_id?: int,
     *     inheritance_price_rules?: array<array{
     *         placements: array<string>,
     *         strategy_type: string,
     *         strategy_adjustment: string,
     *         strategy_value: string|int
     *     }>,
     *     inheritance_restrictions?: array<string>,
     *     menu_order?: int
     * } $data RatePlan data
     * @return int Post ID on success
     * @throws \RuntimeException If creation fails
     */
    public function createRatePlan(array $data): int;

    /**
     * Create a CancellationPolicy CPT.
     *
     * @param array{
     *     title: string,
     *     excerpt?: string,
     *     status?: string,
     *     predefined_rule?: string,
     *     rules?: array<array{
     *         cancelled_min_hours_until_start?: string|int,
     *         cancelled_max_hours_until_start?: string|int,
     *         penalty_type: string,
     *         percentage_amount?: string|int,
     *         fixed_amount?: string|int,
     *         charge_x_nights?: string|int
     *     }>,
     *     menu_order?: int
     * } $data CancellationPolicy data
     * @return int Post ID on success
     * @throws \RuntimeException If creation fails
     */
    public function createCancellationPolicy(array $data): int;

    /**
     * Create a PaymentType CPT.
     *
     * @param array{
     *     title: string,
     *     excerpt?: string,
     *     status?: string,
     *     calculator_type: string,
     *     payment_payable?: bool,
     *     payment_system?: string,
     *     payment_authorization?: bool,
     *     time_for_confirmation?: string|int,
     *     prepayment_type?: string,
     *     prepayment_value?: string|int,
     *     payment_availability_condition?: string,
     *     payment_availability_value?: string|int,
     *     payment_availability_period?: string,
     *     menu_order?: int
     * } $data PaymentType data
     * @return int Post ID on success
     * @throws \RuntimeException If creation fails
     */
    public function createPaymentType(array $data): int;

    /**
     * Create multiple CPT entities in a single transaction.
     *
     * Creates entities in the correct order: AccommodationType → CancellationPolicy → PaymentType → RatePlan
     * Supports index-based references for linking entities in rate plans.
     *
     * Example usage:
     * ```php
     * $result = $creator->createBatch([
     *     'accommodation_types' => [
     *         ['title' => 'Standard Room', 'short_code' => 'STD', ...],
     *         ['title' => 'Deluxe Room', 'short_code' => 'DLX', ...],
     *     ],
     *     'cancellation_policies' => [
     *         ['title' => 'Flexible', ...],
     *     ],
     *     'payment_types' => [
     *         ['title' => 'Full Payment', 'calculator_type' => 'full', ...],
     *     ],
     *     'rate_plans' => [
     *         [
     *             'title' => 'Standard Rate',
     *             'accommodation_types' => [0, 1], // References by index
     *             'cancellation_policy' => 0,      // Reference by index
     *             'payment_types' => [0],           // References by index
     *             ...
     *         ],
     *     ],
     * ]);
     * // Returns: ['accommodation_type_ids' => [123, 124], 'cancellation_policy_ids' => [125], ...]
     * ```
     *
     * @param array{
     *     accommodation_types?: array<array>,
     *     cancellation_policies?: array<array>,
     *     payment_types?: array<array>,
     *     rate_plans?: array<array>
     * } $data Batch data for all CPT types
     * @return array{
     *     accommodation_type_ids: array<int>,
     *     cancellation_policy_ids: array<int>,
     *     payment_type_ids: array<int>,
     *     rate_plan_ids: array<int>
     * } Created post IDs
     * @throws \RuntimeException If batch creation fails (all changes will be rolled back)
     */
    public function createBatch(array $data): array;
}
