<?php
/**
 * Notification Interface
 *
 * Defines the contract for notification sender classes in the plugin.
 * This interface enables a unified API for sending notifications through
 * various channels such as email, SMS, push notifications, and webhooks.
 *
 * @package     WPUltimateSecurity\UltimateSecurity\Contracts
 * @since       1.0.0
 * @author      Ultimate Security Team
 * @license     GPL-2.0-or-later
 */

declare(strict_types=1);

namespace WPUltimateSecurity\UltimateSecurity\Contracts;

/**
 * Interface NotificationInterface
 *
 * Contract for all notification sender classes. Implementations handle the
 * delivery of security-related notifications to users through various channels.
 * This abstraction allows the application to send notifications without being
 * coupled to specific delivery mechanisms.
 *
 * Common use cases:
 * - Sending 2FA verification codes via email or SMS
 * - Alerting administrators about security events
 * - Notifying users about suspicious login attempts
 * - Password reset and account recovery notifications
 *
 * Example implementation:
 * ```php
 * class EmailNotification implements NotificationInterface {
 *     public function send(int $userId, string $subject, string $message, array $data = []): bool {
 *         $user = get_user_by('ID', $userId);
 *         if (!$user) {
 *             return false;
 *         }
 *
 *         $headers = ['Content-Type: text/html; charset=UTF-8'];
 *         return wp_mail($user->user_email, $subject, $message, $headers);
 *     }
 *
 *     public function getType(): string {
 *         return 'email';
 *     }
 * }
 * ```
 *
 * @since 1.0.0
 */
interface NotificationInterface
{
    /**
     * Send a notification to a user.
     *
     * Delivers a notification message to the specified user through this
     * notification channel. The implementation determines the actual delivery
     * mechanism (email, SMS, push, webhook, etc.).
     *
     * Implementation notes:
     * - Should verify the user exists before attempting to send
     * - Should handle failures gracefully and log errors appropriately
     * - Should respect user notification preferences when applicable
     * - Should sanitize all content before sending
     * - May use templates to format the message
     *
     * @since 1.0.0
     *
     * @param int    $userId  The WordPress user ID to send the notification to.
     * @param string $subject The notification subject or title. May be used as
     *                        email subject, SMS header, or push notification title.
     * @param string $message The main content of the notification. Supports HTML
     *                        for email channels, plain text for SMS/push.
     * @param array  $data    Optional. Additional data for the notification, such as:
     *                        - 'template': Template name to use for formatting
     *                        - 'code': Verification code to include
     *                        - 'ip_address': IP address of the event
     *                        - 'user_agent': Browser/device information
     *                        - 'timestamp': Event timestamp
     *                        - 'attachments': Array of file paths (email only)
     *                        - 'priority': Message priority ('high', 'normal', 'low')
     *                        Default empty array.
     *
     * @return bool True if the notification was sent successfully, false on failure.
     */
    public function send(int $userId, string $subject, string $message, array $data = []): bool;

    /**
     * Get the notification channel type.
     *
     * Returns a unique identifier for this notification channel type.
     * This is used to:
     * - Select the appropriate notification sender
     * - Store user channel preferences
     * - Log notification events
     * - Display channel options in the UI
     *
     * Standard types include:
     * - 'email': Email notifications via wp_mail() or SMTP
     * - 'sms': SMS text messages
     * - 'push': Browser push notifications
     * - 'webhook': HTTP webhook calls
     * - 'slack': Slack channel notifications
     * - 'telegram': Telegram bot messages
     *
     * @since 1.0.0
     *
     * @return string The notification channel type identifier.
     */
    public function getType(): string;
}
