<?php

declare(strict_types=1);

namespace Drupal\flowdrop_interrupt\Plugin\InterruptHandler;

use Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface;

/**
 * Base contract for FlowDrop interrupt handler plugins.
 *
 * One plugin per interrupt type. The plugin's ID matches the value stored in
 * `FlowDropInterrupt::type` — for built-in types it also matches the
 * `InterruptType` enum value.
 *
 * Capabilities are layered via decorator interfaces:
 * - {@see HitlInterruptHandlerInterface} — user-facing inbox + resolve form
 * - {@see ScheduledInterruptHandlerInterface} — cron / timer-driven resolution
 * - {@see WebhookInterruptHandlerInterface} — external HTTP callback resolves
 * - {@see QueueDelegationInterruptHandlerInterface} — queue worker resolves
 *
 * A plugin implementing none of the decorator interfaces is purely
 * operational — created and resolved by other code in the runtime, never
 * surfaced to humans.
 *
 * @api
 */
interface InterruptHandlerInterface {

  /**
   * The plugin ID — matches the `FlowDropInterrupt::type` field value.
   */
  public function getId(): string;

  /**
   * Human-readable label for admin / log display.
   *
   * Returns a TranslatableMarkup when one is available so the UI layer can
   * render in the active language.
   */
  public function getLabel(): \Stringable|string;

  /**
   * Free-form description of what this interrupt type represents.
   */
  public function getDescription(): string;

  /**
   * Normalises raw input into the canonical `response_data` shape.
   *
   * Called by resolvers that may receive loosely-typed input (form arrays,
   * HTTP request payloads) before it reaches
   * `InterruptManager::resolveInterrupt()`.
   *
   * @param mixed $raw
   *   Raw input from a resolver.
   * @param \Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface $interrupt
   *   The interrupt being resolved — schema/options/context available here.
   *
   * @return mixed
   *   The canonical `response_data` payload.
   */
  public function normalizeResponse(mixed $raw, FlowDropInterruptInterface $interrupt): mixed;

}
