<?php

declare(strict_types=1);

namespace Drupal\flowdrop_interrupt\Plugin\InterruptHandler;

use Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface;
use Symfony\Component\HttpFoundation\Request;

/**
 * Marks an interrupt handler as resolvable via an inbound HTTP callback.
 *
 * The runtime exposes a generic callback endpoint
 * (`POST /flowdrop/interrupt/callback/{token}`); plugins implementing this
 * interface produce the callback URL their counterpart will hit, validate
 * incoming requests, and extract the response payload.
 *
 * Use for: OAuth callbacks, LLM batch API webhooks, Slack interactions,
 * Stripe webhooks, etc.
 *
 * @api
 */
interface WebhookInterruptHandlerInterface extends InterruptHandlerInterface {

  /**
   * The URL the external system should POST to when ready.
   *
   * Implementations typically include a signed token so validateCallback()
   * can authenticate the request.
   */
  public function getCallbackUrl(FlowDropInterruptInterface $interrupt): string;

  /**
   * Verifies that an inbound request is legitimately resolving this interrupt.
   *
   * Performs signature checks, HMAC, IP allow-list, etc.
   * Defence-in-depth: the routing layer also checks the URL token.
   */
  public function validateCallback(Request $request, FlowDropInterruptInterface $interrupt): bool;

  /**
   * Extracts the response payload from the inbound HTTP request.
   *
   * @return mixed
   *   The raw response, to be passed through `normalizeResponse()`.
   */
  public function extractResponseFromCallback(Request $request, FlowDropInterruptInterface $interrupt): mixed;

}
