<?php
/**
 * Stream Chunk Event Class.
 *
 * Represents a partial content chunk from a streaming response.
 *
 * @package   Agenistrator
 * @since     1.0.0
 * @author    Alex Ruban <alex@maximum.guru>
 * @author    Maximum Software Inc <contact@maximum.software>
 * @license   GPL-3.0-only
 * @link      https://maximum.software/
 *
 * SPDX-FileCopyrightText: 2025-2026 Alex Ruban <alex@maximum.guru>
 * SPDX-FileCopyrightText: 2025-2026 Maximum Software Inc <contact@maximum.software>
 * SPDX-License-Identifier: GPL-3.0-only
 */

namespace Agenistrator\Events;

use Agenistrator\Thread_Event;

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Stream_Chunk_Event class.
 */
class Stream_Chunk_Event extends Thread_Event {

	/**
	 * Message ID
	 *
	 * @var string
	 */
	private $message_id;

	/**
	 * Content chunk
	 *
	 * @var string
	 */
	private $content;

	/**
	 * Sequence number within the message
	 *
	 * @var int
	 */
	private $sequence;

	/**
	 * Whether this is the final chunk
	 *
	 * @var bool
	 */
	private $is_final;

	/**
	 * Constructor.
	 *
	 * @param int    $user_id   The user ID.
	 * @param int    $thread_id The thread ID.
	 * @param string $message_id The message ID.
	 * @param string $content    The content chunk.
	 * @param int    $sequence   The sequence number within the message.
	 * @param bool   $is_final   Whether this is the final chunk.
	 * @since     1.0.0
	 */
	public function __construct( $user_id, $thread_id, $message_id, $content, $sequence, $is_final = false ) {
		parent::__construct( $user_id, $thread_id );
		$this->message_id = $message_id;
		$this->content    = $content;
		$this->sequence   = $sequence;
		$this->is_final   = $is_final;
	}

	/**
	 * Get the event type.
	 *
	 * @return string
	 * @since     1.0.0
	 */
	public function get_type() {
		return 'stream_chunk';
	}

	/**
	 * Get the message ID.
	 *
	 * @return string
	 * @since     1.0.0
	 */
	public function get_message_id() {
		return $this->message_id;
	}

	/**
	 * Get the event data.
	 *
	 * @return array
	 * @since     1.0.0
	 */
	public function get_data() {
		return array(
			'message_id' => $this->message_id,
			'content'    => $this->content,
			'sequence'   => $this->sequence,
			'is_final'   => $this->is_final,
		);
	}

	/**
	 * Get the SSE payload for this event.
	 *
	 * Frontend needs: message_id, content, is_final
	 * Excluded: sequence (internal tracking only)
	 *
	 * @return array
	 * @since     1.0.0
	 */
	public function to_sse_payload() {
		return array_merge(
			parent::to_sse_payload(),
			array(
				'message_id' => $this->message_id,
				'content'    => $this->content,
				'is_final'   => $this->is_final,
			)
		);
	}

	/**
	 * Create an event from array data.
	 *
	 * @param array $data The event data.
	 * @return static
	 * @since     1.0.0
	 */
	public static function from_array( $data ) {
		$event_data = $data['data'] ?? $data;

		$event = new static(
			$data['user_id'],
			$data['thread_id'],
			$event_data['message_id'],
			$event_data['content'],
			$event_data['sequence'],
			$event_data['is_final']
		);

		if ( isset( $data['id'] ) ) {
			$event->set_id( $data['id'] );
		}

		return $event;
	}
}
