#ifndef STATE_MANAGER_H
#define STATE_MANAGER_H

#include "esp_err.h"
#include "motor_control.h"
#include <stdbool.h>

/**
 * @brief Initialize the state manager
 * 
 * Sets up NVS flash and prepares for state operations.
 * Must be called before any other state manager functions.
 * 
 * @return ESP_OK on success, ESP_FAIL on error
 */
esp_err_t state_manager_init(void);

/**
 * @brief Save current motor state to NVS
 * 
 * Saves the current motor mode, speed, last ON state, and user preferences
 * to non-volatile storage for persistence across power cycles.
 * 
 * @return ESP_OK on success, ESP_FAIL on error
 */
esp_err_t state_manager_save(void);

/**
 * @brief Load motor state from NVS and apply restoration logic
 * 
 * Loads saved state from NVS and determines whether to restore the motor
 * based on reset reason and user preferences. Handles:
 * - Power loss recovery
 * - Watchdog reset detection
 * - User manual shutoff preference
 * 
 * @return ESP_OK if state was loaded and applied, ESP_ERR_NVS_NOT_FOUND if no saved state
 */
esp_err_t state_manager_load_and_restore(void);

/**
 * @brief Check if the last reset was due to a watchdog timeout
 * 
 * Distinguishes between true watchdog resets (software issues) and
 * other resets like power loss or external reset.
 * 
 * @return true if reset was due to watchdog timeout, false otherwise
 */
bool state_manager_was_watchdog_reset(void);

/**
 * @brief Get human-readable reset reason string
 * 
 * @return String describing the reset reason
 */
const char* state_manager_get_reset_reason_string(void);

/**
 * @brief Clear all saved state from NVS
 * 
 * Removes all motor state data from NVS. Useful for factory reset
 * or debugging purposes.
 * 
 * @return ESP_OK on success, ESP_FAIL on error
 */
esp_err_t state_manager_clear_all(void);

/**
 * @brief Save only the "last ON" state to NVS
 * 
 * Saves just the last known good motor state for the ON button functionality.
 * This is lighter weight than saving the full state.
 * 
 * @param mode Motor mode (MOTOR_EXHAUST or MOTOR_INTAKE)
 * @param speed Speed percentage (1-100)
 * @return ESP_OK on success, ESP_FAIL on error
 */
esp_err_t state_manager_save_last_on_state(motor_mode_t mode, int speed);

/**
 * @brief Load only the "last ON" state from NVS
 * 
 * @param mode Pointer to store the loaded mode
 * @param speed Pointer to store the loaded speed
 * @return ESP_OK if loaded successfully, ESP_ERR_NVS_NOT_FOUND if not found
 */
esp_err_t state_manager_load_last_on_state(motor_mode_t* mode, int* speed);

/**
 * @brief Check if user manually turned off the motor
 * 
 * Used to determine restoration behavior - if user manually turned off,
 * the motor should stay off after power restoration.
 * 
 * @return true if user manually turned off, false otherwise
 */
bool state_manager_get_user_turned_off(void);

/**
 * @brief Set the user turned off flag
 * 
 * @param turned_off true if user manually turned off, false otherwise
 * @return ESP_OK on success, ESP_FAIL on error
 */
esp_err_t state_manager_set_user_turned_off(bool turned_off);

/**
 * @brief Get detailed state information for debugging
 * 
 * Provides comprehensive information about the saved state and
 * reset conditions for troubleshooting.
 * 
 * @param info_buffer Buffer to store the information string
 * @param buffer_size Size of the info buffer
 * @return ESP_OK on success, ESP_FAIL on error
 */
esp_err_t state_manager_get_debug_info(char* info_buffer, size_t buffer_size);

/**
 * @brief Check if NVS contains any saved motor state
 * 
 * @return true if saved state exists, false otherwise
 */
bool state_manager_has_saved_state(void);

#endif // STATE_MANAGER_H