namespace w4c_workflows.Models.Nodes;

// ---------------------------------------------------------------------------
// A declarative REST connector definition attached to a blueprint. It is what
// turns a plain catalog entry into a runnable integration node without a new C#
// executor per service: the blueprint says WHICH request to make, and the shared
// RestConnectorExecutor makes it (egress-vetted, quota-metered) and maps the
// response. Adding an integration should be data, not code.
//
// The URL is a template. `{name}` resolves from the node's (already
// interpolated) parameters; `{credential.field}` resolves from the field of the
// credential the blueprint references. Example (Telegram):
//
//   baseUrl + path = "https://api.telegram.org" + "/bot{credential.token}/{operation}"
//
// Body/query come from a parameter holding a JSON object, so per-operation
// payloads stay in the workflow, not in the connector.
//
// A connector may declare a credential alias (injected by the shared executor
// through the credential type's strategy) and a success/error envelope
// (`successPath`/`errorPath`/`errorCodeMap`) for services that report failure in
// a HTTP 200 body. Both are data, so no provider-specific code enters the engine.
// ---------------------------------------------------------------------------

/// <summary>Where a connector gets its request body/query and how it maps the response.</summary>
public sealed record NodeConnector
{
    /// <summary>Scheme + host (may itself contain <c>{param}</c>/<c>{credential.field}</c>).</summary>
    public string BaseUrl { get; init; } = string.Empty;

    /// <summary>Path template appended to <see cref="BaseUrl"/>.</summary>
    public string Path { get; init; } = string.Empty;

    /// <summary>HTTP method, e.g. <c>POST</c>.</summary>
    public string Method { get; init; } = "POST";

    /// <summary>Request body encoding: <c>json</c>, <c>form</c> or <c>none</c>.</summary>
    public string ContentType { get; init; } = "json";

    /// <summary>Parameter holding the JSON object sent as the body (null to send none).</summary>
    public string? BodyParameter { get; init; } = "body";

    /// <summary>Parameter holding a JSON object appended as query parameters.</summary>
    public string? QueryParameter { get; init; } = "query";

    /// <summary>Credential alias whose data backs <c>{credential.*}</c> placeholders.</summary>
    public string? CredentialAlias { get; init; }

    /// <summary>Dot path in the JSON response that holds the payload (e.g. <c>result</c>).</summary>
    public string? ResponsePath { get; init; }

    /// <summary>
    /// Dot path whose truthy value marks a successful response envelope (e.g.
    /// <c>ok</c>). When set, a body that reports failure at HTTP 200 is turned
    /// into a <see cref="NodeFailure"/> instead of a success item — some services
    /// carry the outcome in the payload, not the status code. Data, not provider
    /// code: the path lives in the connector JSON.
    /// </summary>
    public string? SuccessPath { get; init; }

    /// <summary>
    /// Dot path to the service error value used when <see cref="SuccessPath"/> is
    /// falsy or missing (e.g. <c>error</c>). It is mapped through
    /// <see cref="ErrorCodeMap"/> and included in the failure message.
    /// </summary>
    public string? ErrorPath { get; init; }

    /// <summary>Dot path to extra error detail (e.g. the scopes a token is missing).</summary>
    public string? ErrorDetailsPath { get; init; }

    /// <summary>
    /// Maps a service error value (read from <see cref="ErrorPath"/>) to our
    /// stable failure code. Unmapped values fall back to <c>connector_error</c>,
    /// so adding an error code stays a data change.
    /// </summary>
    public Dictionary<string, string>? ErrorCodeMap { get; init; }
}