<?php
/**
 * Event Repository Interface
 *
 * Interface for event repository operations
 *
 * @package NemtlyBooking
 * @since   PBOOKING_SINCE
 */

namespace NemtlyBooking\Interfaces;

/**
 * Event Repository Interface
 *
 * @since PBOOKING_SINCE
 */
interface Event_Repository_Interface extends Repository_Interface {

    /**
     * Find 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 find_by_date_range( $start_date, $end_date, $args = [] );

    /**
     * Find 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 find_upcoming( $limit = 10, $args = [] );

    /**
     * Find events by status
     *
     * @since PBOOKING_SINCE
     *
     * @param string $status Event status.
     * @param array  $args   Query arguments.
     *
     * @return array Array of event objects.
     */
    public function find_by_status( $status, $args = [] );

    /**
     * Find recurring events
     *
     * @since PBOOKING_SINCE
     *
     * @param array $args Query arguments.
     *
     * @return array Array of event objects.
     */
    public function find_recurring( $args = [] );

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

    /**
     * Find events by location
     *
     * @since PBOOKING_SINCE
     *
     * @param string $location Event location.
     * @param array  $args     Query arguments.
     *
     * @return array Array of event objects.
     */
    public function find_by_location( $location, $args = [] );

    /**
     * Search events
     *
     * @since PBOOKING_SINCE
     *
     * @param string $search_term Search term.
     * @param array  $args        Query arguments.
     *
     * @return array Array of event objects.
     */
    public function search( $search_term, $args = [] );
}
