<?php

declare(strict_types=1);

namespace Drupal\flowdrop_stategraph\ApprovalGate;

use Drupal\flowdrop_stategraph\DTO\Checkpoint;

/**
 * Interface for approval gate operations.
 *
 * Approval gates provide human-in-the-loop functionality, allowing
 * workflows to pause and wait for human approval before continuing.
 *
 * @api
 */
interface ApprovalGateInterface {

  /**
   * Creates a pending approval request.
   *
   * @param string $nodeId
   *   The approval gate node ID.
   * @param \Drupal\flowdrop_stategraph\DTO\Checkpoint $checkpoint
   *   The checkpoint at the approval gate.
   * @param array<string, mixed> $context
   *   Additional context for the approval request.
   *
   * @return string
   *   The approval request ID.
   */
  public function createRequest(
    string $nodeId,
    Checkpoint $checkpoint,
    array $context = [],
  ): string;

  /**
   * Gets the status of an approval request.
   *
   * @param string $requestId
   *   The approval request ID.
   *
   * @return \Drupal\flowdrop_stategraph\ApprovalGate\ApprovalStatus
   *   The current status.
   */
  public function getStatus(string $requestId): ApprovalStatus;

  /**
   * Approves a pending request.
   *
   * @param string $requestId
   *   The approval request ID.
   * @param int|null $userId
   *   The user ID who approved (NULL for system).
   * @param string $notes
   *   Optional approval notes.
   *
   * @return bool
   *   TRUE if successfully approved.
   */
  public function approve(
    string $requestId,
    ?int $userId = NULL,
    string $notes = "",
  ): bool;

  /**
   * Rejects a pending request.
   *
   * @param string $requestId
   *   The approval request ID.
   * @param int|null $userId
   *   The user ID who rejected (NULL for system).
   * @param string $reason
   *   The rejection reason.
   *
   * @return bool
   *   TRUE if successfully rejected.
   */
  public function reject(
    string $requestId,
    ?int $userId = NULL,
    string $reason = "",
  ): bool;

  /**
   * Gets the checkpoint associated with an approval request.
   *
   * @param string $requestId
   *   The approval request ID.
   *
   * @return \Drupal\flowdrop_stategraph\DTO\Checkpoint|null
   *   The checkpoint or NULL if not found.
   */
  public function getCheckpoint(string $requestId): ?Checkpoint;

  /**
   * Lists pending approval requests.
   *
   * @param int $limit
   *   Maximum number to return.
   *
   * @return array<array{id: string, nodeId: string, checkpointId: string, createdAt: int}>
   *   Array of pending request summaries.
   */
  public function listPending(int $limit = 100): array;

}
