<?php

declare(strict_types=1);

namespace Drupal\flowdrop_interrupt\Plugin\InterruptHandler;

use Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface;

/**
 * Marks an interrupt handler as time/condition driven.
 *
 * A cron sweep (or any periodic process) calls `shouldResolveNow()` on each
 * pending interrupt of a Scheduled handler's type; when TRUE, it builds the
 * auto response and resolves the interrupt through the normal
 * `InterruptManager::resolveInterrupt()` path.
 *
 * Typical use cases:
 * - "wake up in N minutes" continuation
 * - retry-with-backoff
 * - polling an external API until result is ready
 *
 * @api
 */
interface ScheduledInterruptHandlerInterface extends InterruptHandlerInterface {

  /**
   * The next scheduled sweep time, or NULL if no sweep is currently due.
   *
   * Used by a sweeper to short-circuit interrupts that aren't ready to
   * resolve. Returning NULL means "skip me on this sweep" — useful for
   * polling intervals.
   *
   * @return int|null
   *   Unix timestamp, or NULL.
   */
  public function getNextSweepAt(FlowDropInterruptInterface $interrupt): ?int;

  /**
   * Tests whether the interrupt should resolve right now.
   *
   * @param \Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface $interrupt
   *   The interrupt being checked.
   *
   * @return bool
   *   TRUE to resolve; FALSE to leave pending.
   */
  public function shouldResolveNow(FlowDropInterruptInterface $interrupt): bool;

  /**
   * Produces the response data for an automatic resolve.
   *
   * Called when the sweeper resolves this interrupt automatically.
   *
   * @return mixed
   *   The response payload, conforming to `getResponseSchema()`.
   */
  public function buildAutoResponse(FlowDropInterruptInterface $interrupt): mixed;

}
