<?php

declare(strict_types=1);

namespace Drupal\flowdrop_session\Service;

use Drupal\flowdrop_session\Entity\FlowDropSessionInterface;
use Drupal\flowdrop_session\Entity\FlowDropSessionMessageInterface;
use Drupal\flowdrop_workflow\WorkflowDefinitionInterface;

/**
 * Interface for the session service.
 *
 * @internal
 */
interface SessionServiceInterface {

  /**
   * Adds a log message to the session.
   *
   * @param \Drupal\flowdrop_session\Entity\FlowDropSessionInterface $session
   *   The session entity.
   * @param string $content
   *   The log message content.
   * @param string|null $node_id
   *   The node ID this log relates to.
   * @param string $level
   *   The log level (info, warning, error, debug).
   * @param array<string, mixed> $metadata
   *   Optional additional metadata.
   * @param string|null $executionId
   *   Optional execution ID to link the log message to a pipeline run.
   *
   * @return \Drupal\flowdrop_session\Entity\FlowDropSessionMessageInterface
   *   The created message entity.
   *
   * @throws \Drupal\Core\Entity\EntityStorageException
   *   If the entity cannot be saved.
   */
  public function addLogMessage(
    FlowDropSessionInterface $session,
    string $content,
    ?string $node_id = NULL,
    string $level = 'info',
    array $metadata = [],
    ?string $executionId = NULL,
  ): FlowDropSessionMessageInterface;

  /**
   * Adds a system message to the session.
   *
   * @param \Drupal\flowdrop_session\Entity\FlowDropSessionInterface $session
   *   The session entity.
   * @param string $content
   *   The message content.
   * @param array<string, mixed> $metadata
   *   Optional metadata.
   * @param string|null $executionId
   *   Optional execution ID to link the message to a pipeline run.
   *
   * @return \Drupal\flowdrop_session\Entity\FlowDropSessionMessageInterface
   *   The created message entity.
   *
   * @throws \Drupal\Core\Entity\EntityStorageException
   *   If the entity cannot be saved.
   */
  public function addSystemMessage(
    FlowDropSessionInterface $session,
    string $content,
    array $metadata = [],
    ?string $executionId = NULL,
  ): FlowDropSessionMessageInterface;

  /**
   * Adds an assistant message to the session.
   *
   * @param \Drupal\flowdrop_session\Entity\FlowDropSessionInterface $session
   *   The session entity.
   * @param string $content
   *   The message content.
   * @param string|null $node_id
   *   The node ID this message relates to.
   * @param array<string, mixed> $metadata
   *   Optional metadata.
   *
   * @return \Drupal\flowdrop_session\Entity\FlowDropSessionMessageInterface
   *   The created message entity.
   *
   * @throws \Drupal\Core\Entity\EntityStorageException
   *   If the entity cannot be saved.
   */
  public function addAssistantMessage(
    FlowDropSessionInterface $session,
    string $content,
    ?string $node_id = NULL,
    array $metadata = [],
  ): FlowDropSessionMessageInterface;

  /**
   * Returns sessions for a given workflow.
   *
   * @param string $workflow_id
   *   The workflow entity ID.
   * @param int|null $user_id
   *   Optional user ID to filter by owner.
   * @param int $limit
   *   Maximum number of sessions to return.
   * @param int $offset
   *   Number of sessions to skip.
   *
   * @return array<\Drupal\flowdrop_session\Entity\FlowDropSessionInterface>
   *   Array of session entities sorted by created DESC.
   */
  public function getSessionsForWorkflow(
    string $workflow_id,
    ?int $user_id = NULL,
    int $limit = 20,
    int $offset = 0,
  ): array;

  /**
   * Checks whether a workflow contains a chat input node.
   *
   * @param \Drupal\flowdrop_workflow\WorkflowDefinitionInterface $workflow
   *   The workflow entity.
   *
   * @return bool
   *   TRUE if the workflow has a chat input node, FALSE otherwise.
   */
  public function hasChatInputNode(WorkflowDefinitionInterface $workflow): bool;

}
