<?php

declare(strict_types=1);

namespace Drupal\flowdrop_session\Entity;

use Drupal\Core\Entity\ContentEntityInterface;
use Drupal\Core\Entity\EntityChangedInterface;
use Drupal\flowdrop_workflow\WorkflowDefinitionInterface;
use Drupal\user\EntityOwnerInterface;

/**
 * Interface for FlowDrop Session entities.
 *
 * A session represents an isolated execution environment for a workflow.
 * Sessions maintain conversation history and allow interactive execution.
 *
 * @internal
 *   This class is not part of the public API and may change without notice.
 */
interface FlowDropSessionInterface extends ContentEntityInterface, EntityChangedInterface, EntityOwnerInterface {

  /**
   * Gets the session name.
   *
   * @return string
   *   The session name.
   */
  public function getName(): string;

  /**
   * Sets the session name.
   *
   * @param string $name
   *   The session name.
   *
   * @return static
   *   The session entity.
   */
  public function setName(string $name): static;

  /**
   * Gets the display label: the name suffixed with the entity ID.
   *
   * Auto-generated names are just the workflow label (e.g. "Calculator
   * User"), so the ID is appended for disambiguation ("Calculator User
   * #523") wherever sessions are listed. Idempotent: a name that already
   * ends with the ID suffix is returned unchanged.
   *
   * @return string
   *   The display label.
   */
  public function getDisplayLabel(): string;

  /**
   * Gets the workflow ID.
   *
   * @return string
   *   The workflow ID.
   */
  public function getWorkflowId(): string;

  /**
   * Sets the workflow ID.
   *
   * @param string $workflow_id
   *   The workflow ID.
   *
   * @return static
   *   The session entity.
   */
  public function setWorkflowId(string $workflow_id): static;

  /**
   * Gets the associated workflow entity.
   *
   * @return \Drupal\flowdrop_workflow\WorkflowDefinitionInterface|null
   *   The workflow entity or NULL if not found.
   */
  public function getWorkflow(): ?WorkflowDefinitionInterface;

  /**
   * Gets the session status.
   *
   * @return string
   *   The status: idle, running, completed, or failed.
   */
  public function getStatus(): string;

  /**
   * Sets the session status.
   *
   * @param string $status
   *   The status: idle, running, completed, or failed.
   *
   * @return static
   *   The session entity.
   */
  public function setStatus(string $status): static;

  /**
   * Gets the session metadata.
   *
   * @return array<string, mixed>
   *   The metadata array.
   */
  public function getMetadata(): array;

  /**
   * Sets the session metadata.
   *
   * @param array<string, mixed> $metadata
   *   The metadata array.
   *
   * @return static
   *   The session entity.
   */
  public function setMetadata(array $metadata): static;

  /**
   * Gets the current pipeline ID if execution is running.
   *
   * @return int|null
   *   The pipeline ID or NULL.
   */
  public function getCurrentPipelineId(): ?int;

  /**
   * Sets the current pipeline ID.
   *
   * @param int|null $pipeline_id
   *   The pipeline ID or NULL to clear.
   *
   * @return static
   *   The session entity.
   */
  public function setCurrentPipelineId(?int $pipeline_id): static;

  /**
   * Checks if the session is idle.
   *
   * @return bool
   *   TRUE if idle, FALSE otherwise.
   */
  public function isIdle(): bool;

  /**
   * Checks if the session is running.
   *
   * @return bool
   *   TRUE if running, FALSE otherwise.
   */
  public function isRunning(): bool;

  /**
   * Checks if the session completed successfully.
   *
   * @return bool
   *   TRUE if completed, FALSE otherwise.
   */
  public function isCompleted(): bool;

  /**
   * Checks if the session failed.
   *
   * @return bool
   *   TRUE if failed, FALSE otherwise.
   */
  public function isFailed(): bool;

  /**
   * Gets the execution mode.
   *
   * @return string
   *   The execution mode: sync or async.
   */
  public function getExecutionMode(): string;

  /**
   * Sets the execution mode.
   *
   * @param string $execution_mode
   *   The execution mode: sync or async.
   *
   * @return static
   *   The session entity.
   */
  public function setExecutionMode(string $execution_mode): static;

  /**
   * Gets the orchestrator settings.
   *
   * @return array<string, mixed>
   *   The orchestrator settings array.
   */
  public function getOrchestratorSettings(): array;

  /**
   * Sets the orchestrator settings.
   *
   * @param array<string, mixed> $settings
   *   The orchestrator settings array.
   *
   * @return static
   *   The session entity.
   */
  public function setOrchestratorSettings(array $settings): static;

}
