using ZB.MOM.WW.ScadaBridge.Commons.Types.Transport;

namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Transport;

public interface IBundleImporter
{
    /// <summary>
    /// Validates and decrypts the bundle stream, opens a session, and returns session metadata.
    /// </summary>
    /// <param name="bundleStream">Stream containing the bundle zip archive.</param>
    /// <param name="passphrase">Optional passphrase for decrypting an encrypted bundle.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that resolves to session metadata for the loaded bundle.</returns>
    Task<BundleSession> LoadAsync(Stream bundleStream, string? passphrase, CancellationToken ct = default);

    /// <summary>
    /// Diffs the loaded bundle against the target database and returns a per-artifact preview.
    /// </summary>
    /// <param name="sessionId">Session id returned by <see cref="LoadAsync"/>.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that resolves to a per-artifact import preview with conflict details.</returns>
    Task<ImportPreview> PreviewAsync(Guid sessionId, CancellationToken ct = default);

    /// <summary>
    /// Applies the chosen conflict resolutions and commits the import transaction.
    /// </summary>
    /// <param name="sessionId">Session id returned by <see cref="LoadAsync"/>.</param>
    /// <param name="resolutions">Per-artifact conflict resolutions from the preview step.</param>
    /// <param name="user">Username of the operator performing the import, stamped in audit rows.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <param name="nameMap">
    /// The operator-supplied resolution of every source-environment site and connection
    /// name the bundle references (M8 D1). Each entry is either
    /// <see cref="MappingAction.MapToExisting"/> (bind to an existing target site/connection)
    /// or <see cref="MappingAction.CreateNew"/> (create one from the bundle payload). A
    /// site or connection that the bundle references but that has no explicit entry here is
    /// auto-matched against the target by identity (existing → MapToExisting, otherwise
    /// CreateNew). Trailing optional parameter — null is normalised to
    /// <see cref="BundleNameMap.Empty"/> so callers that carry no site/instance payload
    /// (e.g. central-config-only bundles) keep working unchanged.
    /// </param>
    /// <returns>A task that resolves to the result of the committed import transaction.</returns>
    Task<ImportResult> ApplyAsync(
        Guid sessionId,
        IReadOnlyList<ImportResolution> resolutions,
        string user,
        CancellationToken ct = default,
        BundleNameMap? nameMap = null);
}