/**
 * @file cards.h
 * @brief RFID Card database management for Minecraft Orb
 *
 * Provides structures and functions for storing and retrieving
 * quest card data from ESP32 NVS (Non-Volatile Storage).
 */

#ifndef CARDS_H
#define CARDS_H

#include <Arduino.h>
#include "config.h"

/**
 * @brief Quest card data structure
 *
 * Stores RFID card UID along with quest metadata.
 */
struct QuestCard {
    byte uid[MAX_UID_LEN];      // Card UID bytes
    byte uidLength;             // Actual UID length (4 or 7)
    char name[CARD_NAME_LEN];   // Quest name
    char clue[CARD_CLUE_LEN];   // Clue/description text
};

/**
 * @brief Initialize the card database
 *
 * Opens NVS namespace and loads card count.
 */
void initCardDatabase();

/**
 * @brief Get the number of stored cards
 *
 * Returns:
 *     int: Number of cards in database
 */
int getCardCount();

/**
 * @brief Find a card by UID
 *
 * Args:
 *     uid: Pointer to UID bytes
 *     uidLength: Length of UID
 *     card: Pointer to QuestCard to fill if found
 *
 * Returns:
 *     int: Card index if found, -1 if not found
 */
int findCardByUID(byte* uid, byte uidLength, QuestCard* card);

/**
 * @brief Add a new card to the database
 *
 * Args:
 *     card: Pointer to QuestCard to add
 *
 * Returns:
 *     bool: true if added successfully
 */
bool addCard(QuestCard* card);

/**
 * @brief Delete a card by index
 *
 * Args:
 *     index: Card index to delete
 *
 * Returns:
 *     bool: true if deleted successfully
 */
bool deleteCard(int index);

/**
 * @brief Get a card by index
 *
 * Args:
 *     index: Card index
 *     card: Pointer to QuestCard to fill
 *
 * Returns:
 *     bool: true if card exists at index
 */
bool getCard(int index, QuestCard* card);

/**
 * @brief Clear all cards from database
 */
void clearAllCards();

/**
 * @brief Format UID as hex string
 *
 * Args:
 *     uid: Pointer to UID bytes
 *     uidLength: Length of UID
 *     buffer: Output buffer (must be at least uidLength*3)
 */
void formatUID(byte* uid, byte uidLength, char* buffer);

/**
 * @brief Compare two UIDs
 *
 * Args:
 *     uid1: First UID
 *     len1: First UID length
 *     uid2: Second UID
 *     len2: Second UID length
 *
 * Returns:
 *     bool: true if UIDs match
 */
bool compareUID(byte* uid1, byte len1, byte* uid2, byte len2);

#endif // CARDS_H