<?php
/**
 * Standard Field Definitions
 *
 * Centralized, reusable field definitions for triggers and actions.
 * Eliminates duplication across trigger definition files.
 *
 * @package Sequensy
 * @since 2.0.0
 */

declare(strict_types=1);

namespace Sequensy\Triggers\Fields;

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

/**
 * Class StandardFields
 *
 * Provides centralized field definitions for common data types.
 * Use these methods in trigger/action availableFields() callbacks.
 *
 * @example
 * TriggerDefinitionBuilder::WordPress()
 *     ->availableFields( fn() => StandardFields::user() )
 *     ->build();
 */
final class StandardFields {

	/**
	 * Standard WordPress user fields.
	 *
	 * @return array Field definitions.
	 */
	public static function user(): array {
		return array(
			array(
				'name'        => 'user_id',
				'type'        => 'integer',
				'description' => 'Unique identifier for the user',
				'example'     => '123',
			),
			array(
				'name'        => 'user_email',
				'type'        => 'string',
				'description' => 'Email address of the user',
				'example'     => 'user@example.com',
			),
			array(
				'name'        => 'user_login',
				'type'        => 'string',
				'description' => 'Username of the user',
				'example'     => 'johndoe',
			),
			array(
				'name'        => 'display_name',
				'type'        => 'string',
				'description' => 'Display name for the user',
				'example'     => 'John Doe',
			),
			array(
				'name'        => 'first_name',
				'type'        => 'string',
				'description' => 'First name of the user',
				'example'     => 'John',
			),
			array(
				'name'        => 'last_name',
				'type'        => 'string',
				'description' => 'Last name of the user',
				'example'     => 'Doe',
			),
			array(
				'name'        => 'user_role',
				'type'        => 'string',
				'description' => 'Primary role assigned to the user',
				'example'     => 'subscriber',
			),
		);
	}

	/**
	 * Extended user fields including registration data.
	 *
	 * @return array Field definitions.
	 */
	public static function userExtended(): array {
		return array_merge(
			self::user(),
			array(
				array(
					'name'        => 'user_url',
					'type'        => 'string',
					'description' => 'Website URL provided by the user',
					'example'     => 'https://example.com',
				),
				array(
					'name'        => 'registered',
					'type'        => 'datetime',
					'description' => 'Date and time when the user registered',
					'example'     => '2024-01-15 10:30:00',
				),
			)
		);
	}

	/**
	 * Standard WordPress post fields.
	 *
	 * @return array Field definitions.
	 */
	public static function post(): array {
		return array(
			array(
				'name'        => 'post_id',
				'type'        => 'integer',
				'description' => 'Unique identifier for the post',
				'example'     => '456',
			),
			array(
				'name'        => 'post_title',
				'type'        => 'string',
				'description' => 'Title of the post',
				'example'     => 'My Blog Post',
			),
			array(
				'name'        => 'post_content',
				'type'        => 'string',
				'description' => 'Content of the post',
				'example'     => 'This is the post content...',
			),
			array(
				'name'        => 'post_excerpt',
				'type'        => 'string',
				'description' => 'Excerpt of the post',
				'example'     => 'A short summary...',
			),
			array(
				'name'        => 'post_type',
				'type'        => 'string',
				'description' => 'Type of the post',
				'example'     => 'post',
			),
			array(
				'name'        => 'post_status',
				'type'        => 'string',
				'description' => 'Status of the post',
				'example'     => 'publish',
			),
			array(
				'name'        => 'post_author',
				'type'        => 'integer',
				'description' => 'ID of the post author',
				'example'     => '1',
			),
			array(
				'name'        => 'post_date',
				'type'        => 'datetime',
				'description' => 'Date the post was published',
				'example'     => '2024-01-15 10:30:00',
			),
			array(
				'name'        => 'post_url',
				'type'        => 'string',
				'description' => 'URL of the post',
				'example'     => 'https://example.com/my-post',
			),
		);
	}

	/**
	 * Standard WordPress comment fields.
	 *
	 * @return array Field definitions.
	 */
	public static function comment(): array {
		return array(
			array(
				'name'        => 'comment_id',
				'type'        => 'integer',
				'description' => 'Unique identifier for the comment',
				'example'     => '789',
			),
			array(
				'name'        => 'comment_author',
				'type'        => 'string',
				'description' => 'Name of the comment author',
				'example'     => 'Jane Smith',
			),
			array(
				'name'        => 'comment_author_email',
				'type'        => 'string',
				'description' => 'Email of the comment author',
				'example'     => 'jane@example.com',
			),
			array(
				'name'        => 'comment_content',
				'type'        => 'string',
				'description' => 'Content of the comment',
				'example'     => 'Great post!',
			),
			array(
				'name'        => 'comment_date',
				'type'        => 'datetime',
				'description' => 'Date and time the comment was submitted',
				'example'     => '2024-01-15 14:30:00',
			),
			array(
				'name'        => 'comment_post_id',
				'type'        => 'integer',
				'description' => 'ID of the post the comment belongs to',
				'example'     => '456',
			),
		);
	}

	/**
	 * Email marketing subscriber fields.
	 * Common fields for Mailchimp, Kit, Campaign Monitor, etc.
	 *
	 * @return array Field definitions.
	 */
	public static function subscriber(): array {
		return array(
			array(
				'name'        => 'email',
				'type'        => 'string',
				'description' => 'Subscriber email address',
				'example'     => 'subscriber@example.com',
			),
			array(
				'name'        => 'first_name',
				'type'        => 'string',
				'description' => 'Subscriber first name',
				'example'     => 'John',
			),
			array(
				'name'        => 'last_name',
				'type'        => 'string',
				'description' => 'Subscriber last name',
				'example'     => 'Doe',
			),
		);
	}

	/**
	 * Form submission fields.
	 * Common fields for form plugins.
	 *
	 * @return array Field definitions.
	 */
	public static function formSubmission(): array {
		return array(
			array(
				'name'        => 'form_id',
				'type'        => 'integer',
				'description' => 'Unique identifier for the form',
				'example'     => '1',
			),
			array(
				'name'        => 'form_title',
				'type'        => 'string',
				'description' => 'Title of the form',
				'example'     => 'Contact Form',
			),
			array(
				'name'        => 'submission_id',
				'type'        => 'integer',
				'description' => 'Unique identifier for the submission',
				'example'     => '123',
			),
			array(
				'name'        => 'submission_date',
				'type'        => 'datetime',
				'description' => 'Date and time of submission',
				'example'     => '2024-01-15 14:30:00',
			),
		);
	}
}
