<?php

declare(strict_types=1);

namespace Drupal\flowdrop_orchestration\Exception;

/**
 * Interface for interrupt exceptions that pause workflow execution.
 *
 * Interrupt exceptions are special exceptions that indicate a workflow node
 * needs to pause execution and wait for external input (typically user input
 * in a human-in-loop scenario).
 *
 * Unlike regular exceptions, interrupt exceptions should NOT be treated as
 * failures. Instead, they signal that:
 * - The workflow should be paused (not failed).
 * - The interrupt details should be returned to the caller.
 * - The workflow can be resumed once the interrupt is resolved.
 *
 * @see \Drupal\flowdrop_interrupt\Exception\InterruptRequiredException
 *
 * @api
 */
interface InterruptExceptionInterface extends \Throwable {

  /**
   * Gets the unique identifier of the interrupt.
   *
   * @return string
   *   The interrupt UUID.
   */
  public function getInterruptId(): string;

  /**
   * Gets the type of interrupt.
   *
   * @return string
   *   The interrupt type (e.g., 'confirmation', 'choice', 'text', 'form').
   */
  public function getInterruptType(): string;

  /**
   * Gets the execution context for resuming the workflow.
   *
   * @return array<string, mixed>
   *   The execution context.
   */
  public function getExecutionContext(): array;

  /**
   * Converts the exception to an array for API responses.
   *
   * @return array<string, mixed>
   *   The exception data as an array.
   */
  public function toArray(): array;

}
