/*
 * MTG RFID Companion - LittleFS storage manager
 *
 * Phase 2: Mounts LittleFS at /spiffs on the "storage" partition, seeds the
 * default database files on first boot, and exposes file helpers used by the
 * RFID/cache/web subsystems.
 */

#pragma once

#include "esp_err.h"

#ifdef __cplusplus
extern "C" {
#endif

#define STORAGE_BASE_PATH   "/spiffs"
#define STORAGE_MAPPINGS    STORAGE_BASE_PATH "/mappings.json"
#define STORAGE_CARDS_DIR   STORAGE_BASE_PATH "/cards"

/**
 * @brief Mount LittleFS and seed default files.
 * @return ESP_OK on success.
 */
esp_err_t storage_manager_init(void);

/**
 * @brief Check whether a file exists on the filesystem.
 */
bool storage_file_exists(const char *path);

/**
 * @brief Read an entire file into a heap allocated buffer (caller frees).
 * @param[out] out_buf NULL terminated buffer; NULL and out_len=0 if missing.
 */
esp_err_t storage_read_text(const char *path, char **out_buf, size_t *out_len);

/**
 * @brief Write text (plus terminating newline) to a file atomically.
 */
esp_err_t storage_write_text(const char *path, const char *text);

/**
 * @brief Add/replace a UID->card-name mapping in /spiffs/mappings.json.
 */
esp_err_t storage_manager_bind_uid(const char *uid, const char *card_name);

/**
 * @brief Remove a UID mapping and its cached card JSON/JPG files.
 */
esp_err_t storage_manager_unbind_uid(const char *uid);

/**
 * @brief Lookup a card name for a UID in mappings.json. Caller frees *out.
 * @return ESP_OK and non-NULL *out on success; ESP_ERR_NOT_FOUND otherwise.
 */
esp_err_t storage_manager_lookup_name(const char *uid, char **out);

/**
 * @brief Get partition usage information.
 */
esp_err_t storage_manager_get_info(size_t *total_bytes, size_t *used_bytes);

/**
 * @brief Count number of cached cards (.json and .jpg) in /spiffs/cards.
 */
esp_err_t storage_manager_count_cached(int *json_count, int *jpg_count);

/**
 * @brief Wipe all cached cards and optionally reset mappings.json for a new deck.
 */
esp_err_t storage_manager_clear_all_cards(bool reset_mappings);

#ifdef __cplusplus
}
#endif