<?php
/**
 * Event Service Interface
 *
 * Interface for event service operations
 *
 * @package NemtlyBooking
 * @since   PBOOKING_SINCE
 */

namespace NemtlyBooking\Interfaces;

use NemtlyBooking\Models\Event;

/**
 * Event Service Interface
 *
 * @since PBOOKING_SINCE
 */
interface Event_Service_Interface extends Service_Interface {

    /**
     * Create a new event
     *
     * @since PBOOKING_SINCE
     *
     * @param array $data Event data.
     *
     * @return Event|WP_Error Created event object or error.
     */
    public function create_event( $data );

    /**
     * Update an event
     *
     * @since PBOOKING_SINCE
     *
     * @param int   $event_id Event ID.
     * @param array $data     Updated data.
     *
     * @return Event|WP_Error Updated event object or error.
     */
    public function update_event( $event_id, $data );

    /**
     * Delete an event
     *
     * @since PBOOKING_SINCE
     *
     * @param int $event_id Event ID.
     *
     * @return bool|WP_Error True on success, error on failure.
     */
    public function delete_event( $event_id );

    /**
     * Get events with pagination
     *
     * @since PBOOKING_SINCE
     *
     * @param array $args Query arguments.
     *
     * @return array Array of event objects with pagination info.
     */
    public function get_events( $args = [] );

    /**
     * Get upcoming events
     *
     * @since PBOOKING_SINCE
     *
     * @param int   $limit Number of events to return.
     * @param array $args  Query arguments.
     *
     * @return array Array of event objects.
     */
    public function get_upcoming_events( $limit = 10, $args = [] );

    /**
     * Get events by date range
     *
     * @since PBOOKING_SINCE
     *
     * @param string $start_date Start date.
     * @param string $end_date    End date.
     * @param array  $args        Query arguments.
     *
     * @return array Array of event objects.
     */
    public function get_events_by_date_range( $start_date, $end_date, $args = [] );

    /**
     * Get event statistics
     *
     * @since PBOOKING_SINCE
     *
     * @return array Statistics data.
     */
    public function get_event_statistics();

    /**
     * Validate event data
     *
     * @since PBOOKING_SINCE
     *
     * @param array $data Event data.
     *
     * @return bool|WP_Error True if valid, error on failure.
     */
    public function validate_event_data( $data );

    /**
     * Duplicate an event
     *
     * @since PBOOKING_SINCE
     *
     * @param int $event_id Event ID to duplicate.
     *
     * @return Event|WP_Error Duplicated event object or error.
     */
    public function duplicate_event( $event_id );

    /**
     * Get virtual instances for recurring events
     *
     * @since PBOOKING_SINCE
     *
     * @param int    $event_id   Event ID.
     * @param string $start_date Start date.
     * @param string $end_date   End date.
     *
     * @return array Array of virtual instance objects.
     */
    public function get_virtual_instances( $event_id, $start_date, $end_date );
}
