<?php

namespace AIPT\Api\Chatbot;

/**
 * Interface for chatbot settings management.
 *
 * @package AIPT\Api\Chatbot
 * @since 2.5.0
 */
interface ChatbotSettingsInterface {

    /**
     * Check if chatbot is enabled.
     *
     * @return bool
     */
    public function isEnabled(): bool;

    /**
     * Get all settings.
     *
     * @return array Complete settings array.
     */
    public function getAll(): array;

    /**
     * Get a specific setting section.
     *
     * @param string $section Section name (general, placement, appearance, behavior).
     * @return array Section settings.
     */
    public function getSection(string $section): array;

    /**
     * Get a specific setting value.
     *
     * @param string $key     Dot-notation key (e.g., 'general.bot_name').
     * @param mixed  $default Default value if not set.
     * @return mixed Setting value.
     */
    public function get(string $key, $default = null);

    /**
     * Update settings.
     *
     * @param array $settings Partial or full settings array.
     * @return bool|\WP_Error True on success or a drift error when persistence differs.
     * @throws \InvalidArgumentException If validation fails.
     */
    public function update(array $settings);

    /**
     * Get public settings subset (for storefront widget).
     *
     * @return array Public-safe settings.
     */
    public function getPublicSettings(): array;

    /**
     * Get UI labels in configured language.
     *
     * @return array Translated labels.
     */
    public function getLabels(): array;

    /**
     * Get default settings.
     *
     * @return array Default values.
     */
    public static function getDefaults(): array;
}
