<?php

namespace GriffinForms\Includes\Notifications;

interface NotificationChannelInterface
{
    /**
     * Unique slug for this channel, e.g. 'email'.
     */
    public function getChannelId(): string;

    /**
     * Human-readable label shown in the channel picker, e.g. 'Email'.
     */
    public function getLabel(): string;

    /**
     * The integration_id this channel depends on, or null for always-available channels.
     * Used for the double-registration guard and degraded-card rendering.
     */
    public function getOwningIntegrationId(): ?string;

    /**
     * The form field type required for field-based recipients, e.g. 'inputemail', 'inputphone'.
     * Return null if this channel does not support field-based recipients.
     */
    public function getRequiredFieldType(): ?string;

    /**
     * Human-readable label for the recipient input, e.g. 'Email address', 'Phone number'.
     */
    public function getRecipientLabel(): string;

    /**
     * Whether this channel supports manually entered static recipient values.
     */
    public function supportsStaticRecipients(): bool;

    /**
     * Sanitize and validate a raw recipients array from the REST request.
     * Each item is {type: 'field'|'static', value: string}.
     *
     * @param array $raw_recipients Raw array from item_data JSON.
     * @return array Secured recipients ready to store.
     */
    public function secureRecipients(array $raw_recipients): array;

    /**
     * Dispatch the notification. Called by NotificationDispatchWorker.
     *
     * @param array $action    Full saved action (channel, message_id, enabled, order, recipients).
     * @param array $resolved  Recipients with field values already resolved to runtime strings.
     * @param array $context   PostSubmissionPipeline context (submission_id, form_id, field_values, ...).
     */
    public function send(array $action, array $resolved, array $context): void;
}
