/*
* SPDX-License-Identifier: AGPL-3.0-or-later
* Copyright (C) 2025 Sergej Görzen <sergej.goerzen@gmail.com>
* This file is part of OmiLAXR.
*/
using System;
using OmiLAXR.TrackingBehaviours;
using OmiLAXR.Utils;

namespace OmiLAXR.Composers
{
    /// <summary>
    /// Core interface for all analytics statements in the OmiLAXR system.
    /// Represents a single learning analytics event or interaction that can be processed,
    /// transformed, and exported to various endpoints (xAPI, CSV, JSON, etc.).
    /// Statements contain contextual information about learning interactions including
    /// actor data, activity information, and temporal context.
    /// </summary>
    public interface IStatement
    {
        /// <summary>
        /// Gets the origin identifier for this statement.
        /// The origin typically indicates the source component, system, or context
        /// that generated this statement. Used for debugging, filtering, and routing.
        /// </summary>
        /// <returns>String identifier representing the statement's origin</returns>
        string GetOrigin();
        
        /// <summary>
        /// Sets the origin identifier for this statement.
        /// Used to tag statements with their source for tracking and debugging purposes.
        /// </summary>
        /// <param name="origin">String identifier representing the statement's origin</param>
        void SetOrigin(string origin);
        
        /// <summary>
        /// Gets the unique identifier for this statement.
        /// Each statement should have a globally unique identifier (GUID) that
        /// distinguishes it from all other statements in the system.
        /// </summary>
        /// <returns>GUID uniquely identifying this statement</returns>
        Guid GetId();
        
        /// <summary>
        /// Associates this statement with the composer that created it.
        /// Composers are responsible for generating statements from tracked interactions
        /// and events. This linkage enables type-specific processing and validation.
        /// </summary>
        /// <param name="composer">The composer component that generated this statement</param>
        void SetComposer(IComposer composer);
        
        /// <summary>
        /// Checks if this statement was generated by a composer of the specified type.
        /// Useful for filtering and processing statements based on their origin composer,
        /// allowing for type-specific handling in the analytics pipeline.
        /// </summary>
        /// <typeparam name="T">The composer type to check against</typeparam>
        /// <returns>True if the statement was generated by a composer of type T</returns>
        public bool IsFromComposer<T>() where T : IComposer;
        
        /// <summary>
        /// Gets the composer component that generated this statement.
        /// Provides access to the original composer for additional context,
        /// configuration, or type-specific processing needs.
        /// </summary>
        /// <returns>The composer component that created this statement</returns>
        IComposer GetComposer();
        
        /// <summary>
        /// Associates this statement with a specific tracking behaviour component.
        /// Tracking behaviours monitor and respond to various types of interactions
        /// or events in the learning environment. This linkage provides contextual
        /// information about how the statement was triggered.
        /// </summary>
        /// <param name="trackingBehaviour">The tracking behaviour that owns this statement</param>
        void SetOwner(ITrackingBehaviour trackingBehaviour);
        
        /// <summary>
        /// Checks if this statement has been marked as discarded.
        /// Discarded statements are typically filtered out of the pipeline
        /// and not processed by endpoints. Used for implementing business rules,
        /// privacy controls, or data quality filters.
        /// </summary>
        /// <returns>True if the statement has been discarded and should be ignored</returns>
        bool IsDiscarded();
        
        /// <summary>
        /// Marks this statement as discarded, preventing further processing.
        /// Discarded statements are filtered out of the pipeline and not sent
        /// to endpoints. Used for implementing privacy controls, data quality rules,
        /// or dynamic filtering based on runtime conditions.
        /// </summary>
        void Discard();
        
        /// <summary>
        /// Creates a deep copy of this statement with a new unique identifier.
        /// Useful for creating variations of a statement for different contexts,
        /// parallel processing, or backup purposes while maintaining data integrity.
        /// </summary>
        /// <returns>A new statement instance with identical data but different ID</returns>
        IStatement Clone();
        
        /// <summary>
        /// Legacy method for converting statement to string format.
        /// This method has been deprecated in favor of ToJsonString for better
        /// flexibility and standardization on JSON format for data export.
        /// </summary>
        /// <returns>String representation of the statement data</returns>
        [System.Obsolete("Use ToJsonString(bool pretty = false) instead.", true)]
        string ToDataStandardString(string version = null);

        /// <summary>
        /// Converts the statement to JSON string format for export or storage.
        /// JSON format provides standardized, human-readable, and machine-parseable
        /// representation of statement data suitable for various endpoints and systems.
        /// </summary>
        /// <param name="pretty">Whether to format JSON with indentation for readability</param>
        /// <param name="version">Data standard version</param>
        /// <returns>JSON string representation of the statement</returns>
        string ToJsonString(bool pretty = false, string version = null);
        
        /// <summary>
        /// Converts the statement to a concise string representation for logging or debugging.
        /// Provides essential information about the statement in a compact format
        /// suitable for log files, console output, or diagnostic displays.
        /// </summary>
        /// <returns>Concise string summary of the statement</returns>
        string ToShortString();
        
        /// <summary>
        /// Converts the statement to CSV format for tabular data export.
        /// Enables export to spreadsheet applications, data analysis tools,
        /// and databases that require structured tabular data format.
        /// </summary>
        /// <param name="flatten">Whether to flatten nested objects into separate columns</param>
        /// <returns>CSV format representation of the statement data</returns>
        CsvFormat ToCsvFormat(bool flatten = false, string version = null);
        
        /// <summary>
        /// Gets the timestamp when this statement was created as a formatted string.
        /// Provides standardized time representation for temporal analysis,
        /// sequencing, and chronological ordering of learning events.
        /// </summary>
        /// <returns>Formatted timestamp string representing when the statement was created</returns>
        string GetTimestampString();
        
        /// <summary>
        /// Gets pipeline information from the component that sent this statement.
        /// Provides access to pipeline context including actor data providers,
        /// configuration settings, and other contextual information needed
        /// for statement processing and enrichment.
        /// </summary>
        /// <returns>Pipeline information from the sending component</returns>
        PipelineInfo GetSenderPipelineInfo();
    }
}