<?php
/**
 * The agent event stream (PLAN.md §12.1). Every capability and protocol step
 * records through record(), so no channel can skip it.
 *
 * Never recorded: tokens, assertions, proofs, credentials, raw `sub`s, IPs.
 * `meta` holds small non-secret facts only (e.g. a normalised search term).
 *
 * @package AgentAdapt
 */

defined( 'ABSPATH' ) || exit;

/**
 * Event recorder.
 */
final class AgentAdapt_Events {

	/**
	 * Days events are kept (PLAN.md D9). Filterable; 0 keeps nothing.
	 */
	public const RETENTION_DAYS = 90;

	/**
	 * Record one event.
	 *
	 * @param string                    $event   e.g. session.started, product.viewed.
	 * @param AgentAdapt_Context|null    $context Request context (null before a Session exists).
	 * @param array<string,mixed>       $fields  object_id, value, outcome, meta, client_hash, subject_id, session_id.
	 */
	public static function record( string $event, ?AgentAdapt_Context $context = null, array $fields = array() ): void {
		if ( self::retention_days() <= 0 ) {
			return;
		}
		global $wpdb;
		$meta = $fields['meta'] ?? null;
		$wpdb->insert( // phpcs:ignore WordPress.DB.DirectDatabaseQuery
			AgentAdapt_Schema::table( 'events' ),
			array(
				'created'     => time(),
				'client_hash' => (string) ( $fields['client_hash'] ?? ( $context ? $context->client_hash : '' ) ),
				'subject_id'  => (int) ( $fields['subject_id'] ?? ( $context ? $context->subject_id : 0 ) ),
				'session_id'  => (string) ( $fields['session_id'] ?? ( $context ? $context->session_id : '' ) ),
				'user_id'     => (int) ( $context ? $context->user_id : 0 ),
				'channel'     => (string) ( $fields['channel'] ?? ( $context ? $context->channel : 'protocol' ) ),
				'event'       => substr( $event, 0, 40 ),
				'object_id'   => (int) ( $fields['object_id'] ?? 0 ),
				'value'       => isset( $fields['value'] ) ? (float) $fields['value'] : null,
				'outcome'     => substr( (string) ( $fields['outcome'] ?? 'ok' ), 0, 40 ),
				'meta'        => is_array( $meta ) ? wp_json_encode( $meta ) : null,
			)
		);
		if ( $wpdb->insert_id ) {
			/**
			 * An event was recorded. Receives the row id, so listeners that
			 * work later (queued deliveries) read the stored row, not a copy.
			 *
			 * @param int    $id    Event row id.
			 * @param string $event Event name.
			 */
			do_action( 'agentadapt_event_recorded', (int) $wpdb->insert_id, $event );
		}
	}

	/**
	 * Retention in days.
	 */
	public static function retention_days(): int {
		/**
		 * Days to keep agent events. 0 records nothing.
		 *
		 * @param int $days Days.
		 */
		return (int) apply_filters( 'agentadapt_event_retention_days', self::RETENTION_DAYS );
	}

	/**
	 * Remove an account from the events recorded while signed in to it
	 * (WordPress's personal-data eraser). The events stay, so every count
	 * made from them is unchanged. What else they hold (agent, Session,
	 * subject, product or order) no longer leads to the account once its
	 * Sessions are erased too (AgentAdapt_Sessions::erase_account()).
	 *
	 * @param int $user_id Account.
	 * @return int Events changed.
	 */
	public static function anonymise_user( int $user_id ): int {
		if ( $user_id < 1 ) {
			return 0;
		}
		global $wpdb;
		return (int) $wpdb->query( $wpdb->prepare( 'UPDATE %i SET user_id = 0 WHERE user_id = %d', AgentAdapt_Schema::table( 'events' ), $user_id ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery
	}

	/**
	 * Delete events past retention.
	 */
	public static function purge(): void {
		global $wpdb;
		$t = AgentAdapt_Schema::table( 'events' );
		$wpdb->query( $wpdb->prepare( "DELETE FROM %i WHERE created < %d", $t, time() - max( 0, self::retention_days() ) * DAY_IN_SECONDS ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery
	}
}