<?php

/**
 * Channel Interface
 * 
 * Contract for implementing custom notification channels (WhatsApp, SMS, Telegram, etc.)
 * 
 * @package WooNooW\Core\Notifications\Channels
 */

namespace WooNooW\Core\Notifications\Channels;

interface ChannelInterface
{

    /**
     * Get channel unique identifier
     * 
     * @return string Channel ID (e.g., 'whatsapp', 'sms', 'telegram')
     */
    public function get_id();

    /**
     * Get channel display label
     * 
     * @return string Channel label for UI (e.g., 'WhatsApp', 'SMS', 'Telegram')
     */
    public function get_label();

    /**
     * Check if channel is properly configured
     * 
     * Example: API keys are set, credentials are valid, etc.
     * 
     * @return bool True if channel is ready to send notifications
     */
    public function is_configured();

    /**
     * Send notification through this channel
     * 
     * @param string $event_id Event identifier (e.g., 'order_completed', 'newsletter_confirm')
     * @param string $recipient Recipient type ('customer', 'staff')
     * @param array $data Notification context data (order, user, custom vars, etc.)
     * @return bool|array Success status, or array with 'success' and 'message' keys
     */
    public function send($event_id, $recipient, $data);

    /**
     * Get channel configuration fields for admin settings
     * 
     * Optional. Returns array of field definitions for settings UI.
     * 
     * @return array Field definitions (e.g., API key, sender number, etc.)
     */
    public function get_config_fields();
}
