/// Domain Repository Interface: Cart Repository
///
/// Defines the contract for cart data operations.
/// Implementation in data layer handles API and local storage.
library;

import 'package:worker/features/cart/domain/entities/cart_item.dart';

/// Cart Repository Interface
///
/// Provides methods for managing shopping cart items:
/// - Add items to cart
/// - Remove items from cart
/// - Get cart items
/// - Update item quantities
/// - Clear cart
///
/// Implementations should handle:
/// - API-first strategy with local fallback
/// - Offline queue for failed requests
/// - Automatic sync when connection restored
abstract class CartRepository {
  /// Add items to cart
  ///
  /// [itemIds] - Product ERPNext item codes
  /// [quantities] - Quantities for each item
  /// [prices] - Unit prices for each item
  /// [conversionFactors] - Conversion factors (m² to tiles) for each item
  ///
  /// Returns true if successful.
  /// Throws exceptions on failure.
  Future<bool> addToCart({
    required List<String> itemIds,
    required List<double> quantities,
    required List<double> prices,
    List<double?>? conversionFactors,
  });

  /// Remove items from cart
  ///
  /// [itemIds] - Product ERPNext item codes to remove
  ///
  /// Returns true if successful, false otherwise.
  /// Throws exceptions on failure.
  Future<bool> removeFromCart({
    required List<String> itemIds,
  });

  /// Get all cart items
  ///
  /// Returns list of cart items.
  /// Throws exceptions on failure.
  Future<List<CartItem>> getCartItems();

  /// Update item quantity
  ///
  /// [itemId] - Product ERPNext item code
  /// [quantity] - New quantity
  /// [price] - Unit price
  /// [conversionFactor] - Conversion factor (m² to tiles)
  ///
  /// Returns true if successful.
  /// Throws exceptions on failure.
  Future<bool> updateQuantity({
    required String itemId,
    required double quantity,
    required double price,
    double? conversionFactor,
  });

  /// Clear all items from cart
  ///
  /// Returns true if successful, false otherwise.
  /// Throws exceptions on failure.
  Future<bool> clearCart();

  /// Get total cart value
  ///
  /// Returns total amount of all items in cart.
  Future<double> getCartTotal();

  /// Get total cart item count
  ///
  /// Returns total number of items (sum of quantities).
  Future<int> getCartItemCount();
}
