// SPDX-FileCopyrightText: 2026 FocusFlow contributors
// SPDX-License-Identifier: AGPL-3.0-only

part of '../../task_actions.dart';

/// Input for logging work the user already did outside the plan.
///
/// The user may know only a title, or may also know when it happened and how
/// long it took. When time data is present, the resulting surprise task occupies
/// that interval and flexible work overlapping it is pushed out of the way.
class SurpriseTaskLogRequest {
  /// Creates a `SurpriseTaskLogRequest` instance with the values required by its invariants.
  /// Callers should pass already-normalized scheduler data because validation and defaulting belong at the model or service boundary, not in arbitrary UI code.
  const SurpriseTaskLogRequest({
    required this.id,
    required this.title,
    required this.createdAt,
    this.startedAt,
    this.timeUsedMinutes,
    this.projectId = 'inbox',
    this.priority,
    this.reward = RewardLevel.notSet,
    this.difficulty = DifficultyLevel.notSet,
  });

  /// Caller-generated id for the new surprise task.
  ///
  /// This id is also the idempotency key for retrying the same log operation.
  final String id;

  /// User-entered title.
  final String title;

  /// Creation/log timestamp supplied by the caller for testability.
  final DateTime createdAt;

  /// When the surprise work started, if known.
  final DateTime? startedAt;

  /// Minutes spent on the surprise work, if known.
  final int? timeUsedMinutes;

  /// Project id to assign; defaults to inbox when omitted.
  final String projectId;

  /// Optional priority. Null means the user did not set one.
  final PriorityLevel? priority;

  /// Optional reward estimate.
  final RewardLevel reward;

  /// Optional difficulty estimate.
  final DifficultyLevel difficulty;
}
