/// Domain Repository Interface: Products Repository
///
/// Defines the contract for product data operations.
/// The data layer will implement this interface.
library;

import 'package:worker/features/products/domain/entities/category.dart';
import 'package:worker/features/products/domain/entities/product.dart';

/// Products Repository Interface
///
/// Abstract repository defining product data operations.
/// Implemented by the data layer to provide actual data access logic.
abstract class ProductsRepository {
  /// Get all products
  ///
  /// Returns a list of all available products with pagination support.
  /// [limitStart] - Starting index for pagination (default: 0)
  /// [limitPageLength] - Number of items per page (default: 12)
  /// Throws an exception if the operation fails.
  Future<List<Product>> getAllProducts({
    int limitStart = 0,
    int limitPageLength = 12,
  });

  /// Search products by query
  ///
  /// [query] - Search term to filter products
  /// [limitStart] - Starting index for pagination (default: 0)
  /// [limitPageLength] - Number of items per page (default: 12)
  /// Returns filtered list of products matching the query.
  Future<List<Product>> searchProducts(
    String query, {
    int limitStart = 0,
    int limitPageLength = 12,
  });

  /// Get products by category
  ///
  /// [categoryId] - Category ID to filter by
  /// [limitStart] - Starting index for pagination (default: 0)
  /// [limitPageLength] - Number of items per page (default: 12)
  /// Returns list of products in the specified category.
  Future<List<Product>> getProductsByCategory(
    String categoryId, {
    int limitStart = 0,
    int limitPageLength = 12,
  });

  /// Get product by ID
  ///
  /// [id] - Product ID
  /// Returns the product with the specified ID.
  /// Throws an exception if product not found.
  Future<Product> getProductById(String id);

  /// Get all categories
  ///
  /// Returns a list of all product categories.
  Future<List<Category>> getCategories();

  /// Get products with filters
  ///
  /// Fetches products with comprehensive filtering support:
  /// - [itemGroups] - List of product group names to filter by
  /// - [brands] - List of brand names to filter by
  /// - [itemAttributes] - List of attribute filters (attribute + value pairs)
  /// - [searchKeyword] - Search query string
  /// - [limitStart] - Starting index for pagination (default: 0)
  /// - [limitPageLength] - Number of items per page (default: 12)
  /// Returns filtered list of products matching all criteria.
  Future<List<Product>> getProductsWithFilters({
    int limitStart = 0,
    int limitPageLength = 12,
    List<String>? itemGroups,
    List<String>? brands,
    List<Map<String, String>>? itemAttributes,
    String? searchKeyword,
  });
}
