<?php

declare(strict_types=1);

namespace Drupal\flowdrop_interrupt\Message;

use Drupal\flowdrop_interrupt\Enum\InterruptType;

/**
 * Human-in-the-loop interrupt message.
 *
 * Use this when a node needs to collect input from a user matching a JSON
 * Schema — confirmation, choice, free-text, structured forms, anything
 * resolvable through the inbox or a custom HITL surface.
 *
 * Example:
 * @code
 * throw new InterruptRequiredException(new HitlInterruptMessage(
 *   message: 'Approve this article?',
 *   schema: ['type' => 'boolean', 'presentation' => 'confirmation'],
 * ));
 * @endcode
 *
 * The `type` defaults to {@see InterruptType::SchemaForm}; plugins that
 * register their own HITL type may pass that instead so the inbox and
 * resolve form route to their handler.
 *
 * @api
 */
final class HitlInterruptMessage extends AbstractInterruptMessage {

  /**
   * Constructs a new HitlInterruptMessage.
   *
   * @param \Drupal\flowdrop_interrupt\Enum\InterruptType $type
   *   The interrupt type. Defaults to InterruptType::SchemaForm.
   * @param string $message
   *   Human-readable description of the interrupt.
   * @param array<string, mixed> $schema
   *   FlowDrop / JSON Schema describing the expected response shape.
   * @param mixed $defaultValue
   *   Optional pre-filled value.
   * @param int|null $expiresIn
   *   Optional TTL in seconds. NULL means no expiry.
   * @param int|null $assignedToUid
   *   Optional explicit assignee. NULL means the current user (set by the
   *   orchestrator) owns the interrupt.
   * @param array<string, mixed> $context
   *   Opaque payload — never a lookup key.
   */
  public function __construct(
    InterruptType $type = InterruptType::SchemaForm,
    string $message = '',
    public readonly array $schema = [],
    public readonly mixed $defaultValue = NULL,
    public readonly ?int $expiresIn = NULL,
    public readonly ?int $assignedToUid = NULL,
    array $context = [],
  ) {
    parent::__construct($type, $message, $context);
  }

}
