<?php

declare(strict_types=1);

namespace Drupal\flowdrop_interrupt\Service;

use Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface;
use Drupal\flowdrop_interrupt\Enum\InterruptType;

/**
 * Read-side surface of the interrupt service.
 *
 * Extracted from {@see InterruptManagerInterface} so consumers that only need
 * to query interrupts can type-hint a narrower contract. The full
 * `InterruptManagerInterface` still extends this one, so existing callers
 * continue to work unchanged.
 *
 * @api
 */
interface InterruptRepositoryInterface {

  /**
   * Gets an interrupt by UUID.
   *
   * @param string $interrupt_id
   *   The interrupt UUID.
   *
   * @return \Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface|null
   *   The interrupt entity or NULL if not found.
   */
  public function getInterrupt(string $interrupt_id): ?FlowDropInterruptInterface;

  /**
   * Gets pending interrupts for a session.
   *
   * @return array<FlowDropInterruptInterface>
   *   The pending interrupts.
   */
  public function getPendingInterruptsForSession(int $session_id): array;

  /**
   * Gets pending interrupts for a pipeline.
   *
   * @return array<FlowDropInterruptInterface>
   *   The pending interrupts.
   */
  public function getPendingInterruptsForPipeline(string $pipeline_id): array;

  /**
   * Gets pending interrupts for a workflow.
   *
   * @return array<FlowDropInterruptInterface>
   *   The pending interrupts.
   */
  public function getPendingInterruptsForWorkflow(string $workflow_id): array;

  /**
   * Gets all pending interrupts owned by a specific user.
   *
   * @return array<FlowDropInterruptInterface>
   *   The pending interrupts.
   */
  public function getPendingInterruptsForUser(int $user_id): array;

  /**
   * Returns pending interrupts of a specific type.
   *
   * @return array<FlowDropInterruptInterface>
   *   The pending interrupts.
   */
  public function getPendingInterruptsByType(InterruptType $type): array;

  /**
   * Finds pending interrupts gated on the given linked interrupt UUID.
   *
   * @return array<FlowDropInterruptInterface>
   *   The pending interrupts gated on the linked UUID.
   */
  public function getPendingInterruptsLinkedTo(string $linked_interrupt_id): array;

  /**
   * Finds the first pending interrupt of a type on a pipeline.
   */
  public function findPendingInterruptOnPipeline(
    InterruptType $type,
    string $pipeline_id,
  ): ?FlowDropInterruptInterface;

  /**
   * Finds the pending inward signal targeting a pipeline, if any.
   */
  public function findPendingInwardSignal(string $pipelineId): ?FlowDropInterruptInterface;

  /**
   * Counts pending interrupts for a specific user.
   */
  public function countPendingInterruptsForUser(int $user_id): int;

  /**
   * Checks if there are pending interrupts for a session.
   */
  public function hasPendingInterruptsForSession(int $session_id): bool;

  /**
   * Checks if there are pending interrupts for a pipeline.
   */
  public function hasPendingInterruptsForPipeline(string $pipeline_id): bool;

  /**
   * Gets a resolved interrupt for a specific node in a pipeline.
   */
  public function getResolvedInterruptForNode(string $pipeline_id, string $node_id): ?FlowDropInterruptInterface;

}
