<?php

declare(strict_types=1);

namespace Drupal\flowdrop_trigger\Service;

use Drupal\Core\Entity\EntityInterface;

/**
 * Interface for the workflow trigger manager service.
 *
 * @api
 */
interface TriggerManagerInterface {

  /**
   * Process an event and trigger matching workflows.
   *
   * @param string $eventType
   *   The event type (e.g., "entity.insert").
   * @param \Drupal\Core\Entity\EntityInterface $entity
   *   The entity involved in the event.
   * @param array<string, mixed> $context
   *   Additional context data to merge with auto-detected context.
   */
  public function processEvent(
    string $eventType,
    EntityInterface $entity,
    array $context = [],
  ): void;

  /**
   * Process a form event and trigger matching workflows.
   *
   * @param string $eventType
   *   The event type (e.g., "form.submit", "form.validate").
   * @param string $formId
   *   The form ID.
   * @param array<string, mixed> $context
   *   Form context data.
   */
  public function processFormEvent(
    string $eventType,
    string $formId,
    array $context = [],
  ): void;

  /**
   * Process a cron event and trigger matching workflows.
   *
   * @param string $eventType
   *   The event type (e.g., "cron.run").
   * @param array<string, mixed> $context
   *   Cron context data.
   */
  public function processCronEvent(
    string $eventType,
    array $context = [],
  ): void;

  /**
   * Get all active triggers (for admin overview).
   *
   * @return array<string, list<\Drupal\flowdrop_trigger\FlowDropTriggerConfigInterface>>
   *   Triggers grouped by event type. Keys are event type strings,
   *   values are lists of trigger config entities.
   */
  public function getAllActiveTriggers(): array;

  /**
   * Get triggers for a specific workflow.
   *
   * @param string $workflowId
   *   The workflow ID.
   *
   * @return array<\Drupal\flowdrop_trigger\FlowDropTriggerConfigInterface>
   *   Trigger configurations for the workflow.
   */
  public function getTriggersForWorkflow(string $workflowId): array;

}
