using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace Svrnty.CQRS.Events.Abstractions.Schema;

/// <summary>
/// Generates JSON Schema (Draft 7) definitions from CLR types.
/// </summary>
/// <remarks>
/// <para>
/// JSON Schemas enable:
/// - External consumers (non-.NET clients) to understand event structure
/// - Schema validation for incoming/outgoing events
/// - Documentation generation
/// - Code generation for other languages
/// </para>
/// <para>
/// <strong>Implementation Notes:</strong>
/// This is an optional service. If not registered, events will be stored
/// without JSON Schema metadata. This is fine for .NET-to-.NET communication
/// but limits interoperability with non-.NET systems.
/// </para>
/// </remarks>
public interface IJsonSchemaGenerator
{
    /// <summary>
    /// Generates a JSON Schema (Draft 7) for the specified CLR type.
    /// </summary>
    /// <param name="type">The CLR type to generate schema for.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>JSON Schema as a string (JSON format).</returns>
    /// <remarks>
    /// <para>
    /// The generated schema should follow JSON Schema Draft 7 specification.
    /// Include property names, types, required fields, and descriptions from
    /// XML documentation comments if available.
    /// </para>
    /// </remarks>
    Task<string> GenerateSchemaAsync(
        Type type,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Validates a JSON string against a JSON Schema.
    /// </summary>
    /// <param name="jsonData">The JSON data to validate.</param>
    /// <param name="jsonSchema">The JSON Schema to validate against.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if valid, false otherwise.</returns>
    /// <remarks>
    /// <para>
    /// This is an optional operation. Implementations may throw
    /// <see cref="NotSupportedException"/> if validation is not supported.
    /// </para>
    /// </remarks>
    Task<bool> ValidateAsync(
        string jsonData,
        string jsonSchema,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets detailed validation errors if validation fails.
    /// </summary>
    /// <param name="jsonData">The JSON data to validate.</param>
    /// <param name="jsonSchema">The JSON Schema to validate against.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of validation error messages, empty if valid.</returns>
    Task<IReadOnlyList<string>> GetValidationErrorsAsync(
        string jsonData,
        string jsonSchema,
        CancellationToken cancellationToken = default);
}