<?php
declare(strict_types=1);
// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Handles recording of manual (human-authored) notes into the activity log.
 *
 * Intentionally bypasses ACTLOGPRO_Logger::log_activity() so that:
 *  - A custom `created_at` can be supplied for premium backdating.
 *  - An arbitrary display user can be set for premium attribution.
 *
 * All security validation (capability, nonce, premium gating) is performed
 * in the AJAX handler before calling record_note().
 *
 * @since 1.2.0
 */
class ACTLOGPRO_Recorded_Notes {

	/** event_type and object_type value used for all recorded notes. */
	const EVENT_TYPE = 'note';

	/** action value reused from the existing vocabulary. */
	const ACTION = 'added';

	/**
	 * Insert a recorded note into the activity log.
	 *
	 * @param string      $message            Required. The note message text.
	 * @param string      $details            Optional longer details / context.
	 * @param string      $severity           Severity slug (critical|high|medium|low|info). Default 'info'.
	 * @param string|null $event_datetime     Premium: MySQL-formatted datetime string for backdating (YYYY-MM-DD HH:MM:SS).
	 *                                        Null = current site time.
	 * @param int|null    $attributed_user_id Premium: WP user ID to attribute the note to.
	 *                                        Null = currently logged-in admin.
	 * @return int|false  Inserted log row ID on success, false on failure.
	 */
	public static function record_note(
		string $message,
		string $details = '',
		string $severity = 'info',
		?string $event_datetime = null,
		?int $attributed_user_id = null
	) {
		// Ensure required classes are available.
		if ( ! class_exists( 'ACTLOGPRO_Database' ) ) {
			require_once ACTLOGPRO_PLUGIN_DIR . 'includes/class-alp-database.php';
		}
		if ( ! class_exists( 'ACTLOGPRO_Severity' ) ) {
			require_once ACTLOGPRO_PLUGIN_DIR . 'includes/class-alp-severity.php';
		}
		if ( ! class_exists( 'ACTLOGPRO_Logger' ) ) {
			require_once ACTLOGPRO_PLUGIN_DIR . 'includes/class-alp-logger.php';
		}

		// Sanitize message and details (already sanitized in AJAX handler, but defensive).
		$message  = sanitize_text_field( $message );
		$details  = sanitize_textarea_field( $details );
		$severity = ACTLOGPRO_Severity::is_valid( $severity ) ? $severity : ACTLOGPRO_Severity::LEVEL_DEFAULT;

		if ( empty( $message ) ) {
			return false;
		}

		// Resolve the recording admin (always the actual logged-in user).
		$recording_user = wp_get_current_user();
		$recorder = array(
			'user_id'      => $recording_user->ID,
			'user_login'   => $recording_user->user_login,
			'display_name' => $recording_user->display_name,
		);

		// Determine the display user (defaults to recorder; may differ for premium attribution).
		$display_user = $recording_user;
		if ( $attributed_user_id && $attributed_user_id !== $recording_user->ID ) {
			$attr_user = get_userdata( $attributed_user_id );
			if ( $attr_user && $attr_user->ID ) {
				$display_user = $attr_user;
			}
		}

		// Resolve display user role.
		$user_role = 'guest';
		if ( ! empty( $display_user->roles ) && is_array( $display_user->roles ) ) {
			$user_role = reset( $display_user->roles );
		}

		// Resolve timestamp: use supplied datetime or current site time.
		$created_at = ! empty( $event_datetime ) ? $event_datetime : current_time( 'mysql' );

		// Build metadata array.
		$metadata = array(
			'note_message' => $message,
			'source'       => 'recorded_note',
			'recorded_by'  => $recorder,
		);

		if ( ! empty( $details ) ) {
			$metadata['note_details'] = $details;
		}

		// Store attribution metadata when on-behalf-of is used.
		if ( $attributed_user_id && $attributed_user_id !== $recording_user->ID ) {
			$metadata['attributed_to'] = array(
				'user_id'      => $display_user->ID,
				'user_login'   => $display_user->user_login,
				'display_name' => $display_user->display_name,
			);
		}

		// Store backdate metadata when a custom datetime is used.
		if ( ! empty( $event_datetime ) ) {
			$metadata['is_backdated'] = true;
			$metadata['backdated_to'] = $event_datetime;
		}

		// Build the database row — matches the table schema.
		$data = array(
			'user_id'           => $display_user->ID,
			'user_role'         => $user_role,
			'user_login'        => $display_user->user_login,
			'user_display_name' => $display_user->display_name,
			'ip_address'        => ACTLOGPRO_Logger::get_ip_address(),
			'event_type'        => self::EVENT_TYPE,
			'object_type'       => self::EVENT_TYPE,
			'object_id'         => 0,
			'object_name'       => wp_trim_words( $message, 10, '…' ),
			'action'            => self::ACTION,
			'severity'          => $severity,
			'description'       => sprintf(
				/* translators: %s: the note message text */
				__( 'Recorded a note: %s', 'activity-log-pro' ),
				$message
			),
			'metadata'          => maybe_serialize( $metadata ),
			'created_at'        => $created_at,
		);

		return ACTLOGPRO_Database::log_activity( $data );
	}
}