package de.gecheckt.pdf.umbenenner.adapter.in.gui;

import java.nio.file.Path;
import java.util.Objects;

/**
 * Carries the outcome of a successful configuration file write operation.
 * <p>
 * The result separates the written file path from supplementary observations such as
 * API-key preservation events. This allows the GUI to update its header and editor
 * state without inspecting the written file again, and to forward the preservation
 * flag to later warning display logic without mixing that concern into the write
 * implementation itself.
 *
 * @param savedPath              the path to which the file was written; never {@code null}
 * @param apiKeyPreservedForProvider identifier of the provider whose API key was silently
 *                               preserved because the GUI field was left empty while
 *                               the existing property value was non-empty; {@code null}
 *                               when no preservation occurred
 */
public record GuiConfigurationSaveResult(Path savedPath, String apiKeyPreservedForProvider) {

    /**
     * Creates a save result.
     *
     * @param savedPath                  the path that was written; must not be {@code null}
     * @param apiKeyPreservedForProvider provider identifier when key was preserved; may be {@code null}
     */
    public GuiConfigurationSaveResult {
        Objects.requireNonNull(savedPath, "savedPath must not be null");
    }

    /**
     * Creates a save result with no API-key preservation event.
     *
     * @param savedPath the path that was written; must not be {@code null}
     * @return a result without an API-key preservation note
     */
    public static GuiConfigurationSaveResult saved(Path savedPath) {
        return new GuiConfigurationSaveResult(savedPath, null);
    }

    /**
     * Creates a save result that records an API-key preservation event.
     *
     * @param savedPath              the path that was written; must not be {@code null}
     * @param providerIdentifier     the provider for which the key was preserved;
     *                               must not be {@code null}
     * @return a result carrying the preservation note for later display
     */
    public static GuiConfigurationSaveResult savedWithPreservedKey(Path savedPath,
                                                                   String providerIdentifier) {
        Objects.requireNonNull(providerIdentifier, "providerIdentifier must not be null");
        return new GuiConfigurationSaveResult(savedPath, providerIdentifier);
    }

    /**
     * Returns whether an API-key preservation event occurred during this write operation.
     *
     * @return {@code true} when at least one provider API key was silently preserved
     */
    public boolean hasApiKeyPreservationNote() {
        return apiKeyPreservedForProvider != null;
    }
}
