#ifndef AUTH_H
#define AUTH_H

#include <stdbool.h>
#include <freertos/FreeRTOS.h>

#ifdef __cplusplus
extern "C" {
#endif

/// Maximum length of an RFID tag (including null terminator)
#define AUTH_TAG_MAX_LEN 30

/// Event structure emitted after a tag is read
typedef struct {
    char tag[AUTH_TAG_MAX_LEN];  ///< The tag that was read
    bool authorized;             ///< true if the tag is valid
} auth_event_t;

/**
 * @brief Initializes the authentication system.
 * 
 * - Loads configuration (enabled/disabled) from NVS
 * - Starts the Wiegand reader
 * - Emits AUTH_EVENT_INIT with current status
 */
void auth_init(void);

/**
 * @brief Enables or disables RFID-based authentication.
 * 
 * This setting is persisted in NVS. If disabled,
 * all tags will be treated as authorized.
 *
 * @param value true to enable authentication, false to disable
 */
void auth_set_enabled(bool value);

/**
 * @brief Checks whether authentication is currently enabled.
 *
 * @return true if enabled, false if disabled
 */
bool auth_is_enabled(void);

/**
 * @brief Adds a new RFID tag to the authorized list.
 *
 * @param tag The RFID tag (max AUTH_TAG_MAX_LEN-1 characters)
 * @return true if the tag was added successfully,
 *         false if it already exists or is invalid
 */
bool auth_add_tag(const char *tag);

/**
 * @brief Removes an existing RFID tag from the authorized list.
 *
 * @param tag The tag to remove
 * @return true if the tag was removed, false if not found
 */
bool auth_remove_tag(const char *tag);

/**
 * @brief Checks whether a tag is already registered.
 *
 * @param tag The tag to check
 * @return true if the tag exists, false otherwise
 */
bool auth_tag_exists(const char *tag);

/**
 * @brief Logs all currently registered tags via ESP logging.
 */
void auth_list_tags(void);

/**
 * @brief Processes a read RFID tag.
 *
 * - Checks whether it's authorized
 * - Emits AUTH_EVENT_TAG_PROCESSED event
 * - Starts expiration timer if authorized
 *
 * @param tag The tag that was read
 */
void auth_process_tag(const char *tag);

/**
 * @brief Enables registration mode for the next tag read.
 *
 * When registration mode is active, the next tag read
 * will be added to the authorized list automatically.
 * Mode is deactivated after one tag is registered.
 */
void auth_wait_for_tag_registration(void);

/**
 * @brief Returns the total number of registered tags.
 *
 * @return Number of valid tags
 */
int auth_get_tag_count(void);

/**
 * @brief Returns the tag string at the given index.
 *
 * @param index The index (0 ≤ index < auth_get_tag_count())
 * @return Pointer to the tag string, or NULL if index is invalid
 */
const char *auth_get_tag_by_index(int index);

#ifdef __cplusplus
}
#endif

#endif // AUTH_H