/// Domain Repository Interface: Reviews
///
/// Defines the contract for review data operations.
library;

import 'package:worker/features/reviews/domain/entities/review.dart';
import 'package:worker/features/reviews/domain/entities/review_statistics.dart';

/// Reviews repository interface
///
/// Defines methods for managing product reviews:
/// - Fetching reviews for a product
/// - Submitting new reviews
/// - Updating existing reviews
/// - Deleting reviews
abstract class ReviewsRepository {
  /// Get reviews for a specific product
  ///
  /// [itemId] - Product item code
  /// [limitPageLength] - Number of reviews per page (default: 10)
  /// [limitStart] - Pagination offset (default: 0)
  ///
  /// Returns a list of [Review] entities
  ///
  /// Throws:
  /// - [NetworkException] on network errors
  /// - [ServerException] on server errors
  /// - [ParseException] on JSON parsing errors
  Future<List<Review>> getProductReviews({
    required String itemId,
    int limitPageLength = 10,
    int limitStart = 0,
  });

  /// Get review statistics for a product
  ///
  /// [itemId] - Product item code
  ///
  /// Returns [ReviewStatistics] with total count and average rating
  ///
  /// Throws:
  /// - [NetworkException] on network errors
  /// - [ServerException] on server errors
  Future<ReviewStatistics> getProductReviewStatistics({
    required String itemId,
  });

  /// Submit a new review or update an existing one
  ///
  /// [itemId] - Product item code
  /// [rating] - Rating value (0-1 scale for API)
  /// [comment] - Review comment text
  /// [name] - Optional review ID for updates (format: ITEM-{item_id}-{user_email})
  ///
  /// If [name] is provided, the review will be updated.
  /// If [name] is null, a new review will be created.
  ///
  /// Throws:
  /// - [NetworkException] on network errors
  /// - [ServerException] on server errors
  /// - [ValidationException] on invalid data
  /// - [AuthException] if not authenticated
  Future<void> submitReview({
    required String itemId,
    required double rating,
    required String comment,
    String? name,
  });

  /// Delete a review
  ///
  /// [name] - Review ID to delete (format: ITEM-{item_id}-{user_email})
  ///
  /// Throws:
  /// - [NetworkException] on network errors
  /// - [ServerException] on server errors
  /// - [NotFoundException] if review doesn't exist
  /// - [AuthException] if not authenticated or not authorized
  Future<void> deleteReview({
    required String name,
  });
}
