/*
 * ═══════════════════════════════════════════════════════════════════════════════════
 * RESPONSEBUILDER.HPP - Unified Response Generation System
 * ═══════════════════════════════════════════════════════════════════════════════════
 * 
 * 📡 STANDARDIZED COMMUNICATION RESPONSES 📡
 * 
 * This class provides a unified interface for generating consistent JSON responses
 * across all communication protocols (MQTT, WebSocket). It ensures all responses
 * follow the same format and structure.
 * 
 * 🏗️ ARCHITECTURE:
 *   • Static methods for response generation
 *   • Consistent JSON structure across all protocols
 *   • Memory-efficient response building
 *   • Type-safe response categories
 * 
 * 📡 RESPONSE TYPES:
 *   • Success: Successful command execution
 *   • Error: Command execution failures
 *   • Status: System status reports and updates
 *   • Data: Information requests and telemetry
 * 
 * 🔄 RESPONSE STRUCTURE:
 *   {
 *     "status": "OK|ERROR",
 *     "type": "command_type",
 *     "payload": "data_or_message"
 *   }
 * 
 * 📋 USAGE EXAMPLES:
 *   • ResponseBuilder::success("playback", "Started playing melody")
 *   • ResponseBuilder::error("download", "File not found")
 *   • ResponseBuilder::status("telemetry", telemetryData)
 * 
 * 📋 VERSION: 1.0 (Initial unified response system)
 * 📅 DATE: 2025
 * 👨‍💻 AUTHOR: Advanced Bell Systems
 * ═══════════════════════════════════════════════════════════════════════════════════
 */

#pragma once

#include <Arduino.h>
#include <ArduinoJson.h>
#include "../../Player/Player.hpp"  // For PlayerStatus enum

class ResponseBuilder {
public:
    // Response status types
    enum class Status {
        SUCCESS,
        ERROR,
        INFO
    };

    // Main response builders
    static String success(const String& type, const String& payload = "");
    static String success(const String& type, const JsonObject& payload);
    static String error(const String& type, const String& message);
    static String status(const String& type, const JsonObject& data);
    static String status(const String& type, const String& data);

    // Specialized response builders for common scenarios
    static String acknowledgment(const String& commandType);
    static String pong();
    static String deviceStatus(PlayerStatus playerStatus, uint32_t timeElapsedMs, uint64_t projectedRunTime = 0);
    static String melodyList(const String& fileListJson);
    static String downloadResult(bool success, const String& filename = "");
    static String configUpdate(const String& configType);

    // Error response builders
    static String invalidCommand(const String& command);
    static String missingParameter(const String& parameter);
    static String operationFailed(const String& operation, const String& reason = "");
    static String deviceBusy();
    static String unauthorized();

    // Utility methods
    static String buildResponse(Status status, const String& type, const String& payload);
    static String buildResponse(Status status, const String& type, const JsonObject& payload);

private:
    // Internal helper methods
    static const char* statusToString(Status status);
    static StaticJsonDocument<512> _responseDoc;  // Reusable document for efficiency
};