<?php

declare(strict_types=1);

namespace Drupal\flowdrop_session\Entity;

use Drupal\Core\Entity\ContentEntityInterface;

/**
 * Interface for FlowDrop Session Message entities.
 *
 * A message in a session. Messages can be user inputs,
 * assistant responses, system notifications, or execution logs.
 *
 * @internal
 *   This class is not part of the public API and may change without notice.
 */
interface FlowDropSessionMessageInterface extends ContentEntityInterface {

  /**
   * Gets the session ID.
   *
   * @return int
   *   The session ID.
   */
  public function getSessionId(): int;

  /**
   * Sets the session ID.
   *
   * @param int $session_id
   *   The session ID.
   *
   * @return static
   *   The message entity.
   */
  public function setSessionId(int $session_id): static;

  /**
   * Gets the associated session entity.
   *
   * @return \Drupal\flowdrop_session\Entity\FlowDropSessionInterface|null
   *   The session entity or NULL if not found.
   */
  public function getSession(): ?FlowDropSessionInterface;

  /**
   * Gets the message role.
   *
   * @return string
   *   The role: user, assistant, system, or log.
   */
  public function getRole(): string;

  /**
   * Sets the message role.
   *
   * @param string $role
   *   The role: user, assistant, system, or log.
   *
   * @return static
   *   The message entity.
   */
  public function setRole(string $role): static;

  /**
   * Gets the message content.
   *
   * @return string
   *   The message content.
   */
  public function getContent(): string;

  /**
   * Sets the message content.
   *
   * @param string $content
   *   The message content.
   *
   * @return static
   *   The message entity.
   */
  public function setContent(string $content): static;

  /**
   * Gets the message timestamp.
   *
   * @return int
   *   Unix timestamp when the message was created.
   */
  public function getTimestamp(): int;

  /**
   * Gets the associated node ID if this is a log message.
   *
   * @return string|null
   *   The node ID or NULL.
   */
  public function getNodeId(): ?string;

  /**
   * Sets the associated node ID.
   *
   * @param string|null $node_id
   *   The node ID or NULL.
   *
   * @return static
   *   The message entity.
   */
  public function setNodeId(?string $node_id): static;

  /**
   * Gets the message metadata.
   *
   * @return array<string, mixed>
   *   The metadata array containing level, duration, nodeLabel, outputs, etc.
   */
  public function getMessageMetadata(): array;

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

  /**
   * Checks if this is a user message.
   *
   * @return bool
   *   TRUE if user message, FALSE otherwise.
   */
  public function isUserMessage(): bool;

  /**
   * Checks if this is an assistant message.
   *
   * @return bool
   *   TRUE if assistant message, FALSE otherwise.
   */
  public function isAssistantMessage(): bool;

  /**
   * Checks if this is a system message.
   *
   * @return bool
   *   TRUE if system message, FALSE otherwise.
   */
  public function isSystemMessage(): bool;

  /**
   * Checks if this is a log message.
   *
   * @return bool
   *   TRUE if log message, FALSE otherwise.
   */
  public function isLogMessage(): bool;

  /**
   * Gets the message status.
   *
   * @return string
   *   The status: pending, processing, completed, failed, or cancelled.
   */
  public function getStatus(): string;

  /**
   * Sets the message status.
   *
   * @param string $status
   *   The status: pending, processing, completed, failed, or cancelled.
   *
   * @return static
   *   The message entity.
   */
  public function setStatus(string $status): static;

  /**
   * Checks if the message is pending.
   *
   * @return bool
   *   TRUE if status is pending, FALSE otherwise.
   */
  public function isPending(): bool;

  /**
   * Checks if the message is processing.
   *
   * @return bool
   *   TRUE if status is processing, FALSE otherwise.
   */
  public function isProcessing(): bool;

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

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

  /**
   * Checks if the message is cancelled.
   *
   * @return bool
   *   TRUE if status is cancelled, FALSE otherwise.
   */
  public function isCancelled(): bool;

  /**
   * Checks if the message is in a terminal state.
   *
   * @return bool
   *   TRUE if status is completed, failed, or cancelled, FALSE otherwise.
   */
  public function isTerminal(): bool;

  /**
   * Gets the sequence number.
   *
   * @return int
   *   The sequence number.
   */
  public function getSequenceNumber(): int;

  /**
   * Sets the sequence number.
   *
   * @param int $sequence_number
   *   The sequence number.
   *
   * @return static
   *   The message entity.
   */
  public function setSequenceNumber(int $sequence_number): static;

  /**
   * Gets the parent message ID.
   *
   * @return int|null
   *   The parent message ID or NULL.
   */
  public function getParentMessageId(): ?int;

  /**
   * Sets the parent message ID.
   *
   * @param int|null $parent_message_id
   *   The parent message ID or NULL.
   *
   * @return static
   *   The message entity.
   */
  public function setParentMessageId(?int $parent_message_id): static;

  /**
   * Gets the parent message entity.
   *
   * @return \Drupal\flowdrop_session\Entity\FlowDropSessionMessageInterface|null
   *   The parent message entity or NULL.
   */
  public function getParentMessage(): ?FlowDropSessionMessageInterface;

  /**
   * Gets the execution ID.
   *
   * @return string|null
   *   The execution ID or NULL.
   */
  public function getExecutionId(): ?string;

  /**
   * Sets the execution ID.
   *
   * @param string|null $execution_id
   *   The execution ID or NULL.
   *
   * @return static
   *   The message entity.
   */
  public function setExecutionId(?string $execution_id): static;

  /**
   * Gets the retry count.
   *
   * @return int
   *   The retry count.
   */
  public function getRetryCount(): int;

  /**
   * Sets the retry count.
   *
   * @param int $retry_count
   *   The retry count.
   *
   * @return static
   *   The message entity.
   */
  public function setRetryCount(int $retry_count): static;

  /**
   * Increments the retry count.
   *
   * @return static
   *   The message entity.
   */
  public function incrementRetryCount(): static;

}
