<?php

namespace WPPilot;

defined( 'ABSPATH' ) || exit;

/**
 * Immutable value object representing a single WordPress activity event.
 *
 * Each event carries structured metadata (not a free-form description string)
 * so downstream consumers (SPA feed, AI tools, clustering) can filter and
 * reason without regex-parsing prose.
 *
 * Modernization note (from Phase 1 research §4.2): WPFort used free-form
 * string parameters to `wpsec_add_to_activity_log()`. This class provides
 * typed, machine-parseable payloads with a four-level severity model per
 * brief Part 8 (info / notable / important / critical).
 */
final class Activity_Event {

	/** @var string Event type identifier, e.g. 'login_success', 'plugin_activated'. */
	public string $type;

	/**
	 * Four-level severity per brief Part 8:
	 *   info     — routine, de-emphasized
	 *   notable  — worth knowing
	 *   important — needs attention
	 *   critical — urgent
	 *
	 * @var string
	 */
	public string $severity;

	/**
	 * Event category for routing and filtering:
	 * authentication | user | content | plugin | theme | file | security | system
	 *
	 * @var string
	 */
	public string $category;

	/**
	 * Structured, event-type-specific metadata. Always an associative array,
	 * never a free-form string. Examples:
	 *   login_success  → ['user_id'=>1, 'username'=>'admin', 'roles'=>['administrator']]
	 *   plugin_activated → ['plugin_file'=>'foo/foo.php', 'plugin_name'=>'Foo', 'version'=>'1.2']
	 *
	 * @var array<string, mixed>
	 */
	public array $metadata;

	/** @var float Unix timestamp with microseconds (from microtime(true)). */
	public float $timestamp;

	/**
	 * @param string              $type     Event type identifier.
	 * @param string              $severity info|notable|important|critical.
	 * @param string              $category authentication|user|content|plugin|theme|file|security|system.
	 * @param array<string,mixed> $metadata Structured per-event payload.
	 * @param float               $timestamp Optional; defaults to now.
	 */
	public function __construct(
		string $type,
		string $severity,
		string $category,
		array $metadata = array(),
		float $timestamp = 0.0
	) {
		$this->type      = $type;
		$this->severity  = $severity;
		$this->category  = $category;
		$this->metadata  = $metadata;
		$this->timestamp = $timestamp > 0 ? $timestamp : microtime( true );
	}

	/**
	 * Wire format for batch POST to the WPPilot backend.
	 *
	 * @return array<string, mixed>
	 */
	public function to_payload(): array {
		return array(
			'type'      => $this->type,
			'severity'  => $this->severity,
			'category'  => $this->category,
			'metadata'  => $this->metadata,
			'timestamp' => gmdate( 'c', (int) $this->timestamp ),
		);
	}
}