namespace FrameworkDAL.DTO.EIPConversation
{
    /// <summary>
    /// Declares a single parameter to be included in an EIP capability/action HTTP call.
    ///
    /// Used in EIPApiConfig.Parameters to build body, query string, header, or path
    /// values from a mix of fixed literals, engine-managed context values, and
    /// user-supplied input collected during INPUT steps.
    ///
    /// Source semantics (both resolve from context.Variables at runtime):
    ///   FIXED   — literal Value is used as-is
    ///   CONTEXT — value comes from context.Variables[Key] (set by engine: login, prior API response)
    ///   INPUT   — value comes from context.Variables[Key] (collected from user during INPUT steps)
    ///
    /// In semantics:
    ///   body   — included in the JSON request body (default)
    ///   query  — appended to the URL as ?key=value
    ///   header — added as a request header
    ///   path   — substituted in PathTemplate (e.g., "/Orders/{OrderId}")
    /// </summary>
    public class EIPParamDefinitionDTO
    {
        public string Name { get; set; } = "";

        /// <summary>"body" | "query" | "header" | "path"</summary>
        public string In { get; set; } = "body";

        /// <summary>"FIXED" | "CONTEXT" | "INPUT"</summary>
        public string Source { get; set; } = "FIXED";

        /// <summary>Literal value used when Source=FIXED.</summary>
        public string? Value { get; set; }

        /// <summary>Variable name in context.Variables used when Source=CONTEXT or INPUT.</summary>
        public string? Key { get; set; }

        /// <summary>Fallback value when Key is not found in context.Variables.</summary>
        public string? DefaultValue { get; set; }
    }
}