<?php
/**
 * Invoice Repository Interface
 *
 * @package     EasyInvoice
 * @since       1.0.0
 */

namespace EasyInvoice\Interfaces;

use EasyInvoice\Models\Invoice;

/**
 * Invoice Repository Interface
 *
 * Defines the contract for invoice repositories with extensibility for pro features.
 *
 * @since 1.0.0
 */
interface InvoiceRepositoryInterface {
    /**
     * Find invoice by ID
     *
     * @param int $id Invoice ID
     * @return Invoice|null
     */
    public function find($id);
    
    /**
     * Get all invoices
     *
     * @param array $args Optional arguments to filter the results
     * @return array Array of Invoice models
     */
    public function all($args = []);
    
    /**
     * Create a new invoice
     *
     * @param array $data Invoice data
     * @return Invoice|false The created invoice or false on failure
     */
    public function create($data);
    
    /**
     * Update an existing invoice
     *
     * @param int $id The invoice ID
     * @param array $data The invoice data
     * @return Invoice|null The updated invoice model or null if not found
     */
    public function update($id, $data);
    
    /**
     * Delete an invoice
     *
     * @param int $id The invoice ID
     * @return bool True if successful, false otherwise
     */
    public function delete($id);
    
    /**
     * Find invoices by customer ID
     *
     * @param int $customer_id The customer ID
     * @return array Array of Invoice models
     */
    public function findByCustomer($customer_id);
    
    /**
     * Find invoices by status
     *
     * @param string $status The invoice status
     * @return array Array of Invoice models
     */
    public function findByStatus($status);
    
    /**
     * Find invoices due within a date range
     *
     * @param string $start_date The start date in 'Y-m-d' format
     * @param string $end_date The end date in 'Y-m-d' format
     * @return array Array of Invoice models
     */
    public function findByDueDate($start_date, $end_date = null);
    
    /**
     * Count invoices
     *
     * @param array $args Optional arguments to filter the results
     * @return int Number of invoices
     */
    public function count($args = []);
    
    /**
     * Find published invoice by ID
     *
     * @param int $id The invoice ID
     * @return Invoice|null The invoice model or null if not found
     */
    public function findPublished(int $id);
    
    /**
     * Update all existing draft invoices to published status for proper permalinks
     *
     * @return int Number of invoices updated
     */
    public function updateAllExistingInvoices(): int;
} 