<?php
/**
 * User Fields Helper
 *
 * Shared field definitions and context builders for user-related triggers.
 *
 * @package Sequensy\Integrations\WordPress
 * @since 3.0.0
 */

declare(strict_types=1);

namespace Sequensy\Integrations\WordPress\Helpers;

// If this file is called directly, abort.
if ( ! defined( 'WPINC' ) ) {
	die;
}

/**
 * Class UserFields
 *
 * Provides shared user field definitions for triggers and actions.
 */
final class UserFields {

	/**
	 * Get available fields shared by all user-related triggers.
	 *
	 * @return array Available field definitions.
	 */
	public static function available_fields(): array {
		return array(
			array(
				'name'        => 'user_id',
				'type'        => 'integer',
				'description' => __( 'Unique identifier for the user', 'sequensy' ),
				'example'     => '123',
			),
			array(
				'name'        => 'user_email',
				'type'        => 'string',
				'description' => __( 'Email address of the user', 'sequensy' ),
				'example'     => 'user@example.com',
			),
			array(
				'name'        => 'user_login',
				'type'        => 'string',
				'description' => __( 'Username of the user', 'sequensy' ),
				'example'     => 'johndoe',
			),
			array(
				'name'        => 'display_name',
				'type'        => 'string',
				'description' => __( 'Display name for the user', 'sequensy' ),
				'example'     => 'John Doe',
			),
			array(
				'name'        => 'user_role',
				'type'        => 'string',
				'description' => __( 'Primary role assigned to the user', 'sequensy' ),
				'example'     => 'subscriber',
			),
			array(
				'name'        => 'first_name',
				'type'        => 'string',
				'description' => __( 'First name of the user', 'sequensy' ),
				'example'     => 'John',
			),
			array(
				'name'        => 'last_name',
				'type'        => 'string',
				'description' => __( 'Last name of the user', 'sequensy' ),
				'example'     => 'Doe',
			),
			array(
				'name'        => 'user_url',
				'type'        => 'string',
				'description' => __( 'Website URL provided by the user', 'sequensy' ),
				'example'     => 'https://example.com',
			),
			array(
				'name'        => 'registered',
				'type'        => 'datetime',
				'description' => __( 'Date and time when the user registered', 'sequensy' ),
				'example'     => '2024-01-15 10:30:00',
			),
		);
	}

	/**
	 * Build user context from a user ID.
	 *
	 * @param int $user_id WordPress user ID.
	 * @return array|null Context array or null if user not found.
	 */
	public static function build_context( int $user_id ): ?array {
		$user = get_userdata( $user_id );
		if ( ! $user ) {
			return null;
		}

		return array(
			'user_id'      => $user_id,
			'user_email'   => $user->user_email,
			'user_login'   => $user->user_login,
			'display_name' => $user->display_name,
			'user_role'    => ! empty( $user->roles ) ? $user->roles[0] : '',
			'first_name'   => get_user_meta( $user_id, 'first_name', true ),
			'last_name'    => get_user_meta( $user_id, 'last_name', true ),
			'user_url'     => $user->user_url,
			'registered'   => $user->user_registered,
		);
	}
}
