wme-models 0.1.3

//! Article types for the Wikimedia Enterprise API.
//!
//! This module provides the core [`Article`] type used across all Enterprise APIs
//! (On-demand, Snapshot, and Realtime). The same schema is returned by all endpoints,
//! allowing you to process articles from any source without separate parsers.
//!
//! # Article Structure
//!
//! Articles contain comprehensive metadata about a Wikipedia page:
//! - **Identification**: `identifier`, `name`, `url`
//! - **Content**: `abstract_text`, `article_body` (HTML/wikitext)
//! - **Context**: `in_language`, `is_part_of`, `namespace`
//! - **Version**: `version` with editor info and credibility signals
//! - **Categorization**: `categories`, `templates`, `redirects`
//! - **Event metadata**: `event` (Realtime API only)
//!
//! # Handling Duplicates
//!
//! Snapshot and Realtime Batch files may contain duplicate articles (< 1%).
//! When processing, keep the article with the highest `version.identifier`:
//!
//! ```rust
//! use wme_models::Article;
//!
//! fn keep_latest(existing: &Article, incoming: &Article) -> bool {
//!     incoming.version.identifier > existing.version.identifier
//! }
//! ```
//!
//! # Visibility Events
//!
//! The Realtime API may return `visibility-change` events where content is hidden.
//! Check the `visibility` field to determine if text, editor, or comment is visible.

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

use crate::content::ArticleBody;
use crate::metadata::{EventMetadata, Language};
use crate::reference::Reference;
use crate::structured::{Infobox, Section, Table};
use crate::version::{OptionalPreviousVersion, Protection, Version};
use crate::{
    Category, Image, License, Namespace, Redirect, Template, WikidataEntity, WikidataEntityUsage,
};

/// Visibility flags for articles (present on visibility-change events).
///
/// When the editing community flags a revision as containing potentially damaging
/// information, they change its visibility. The three booleans indicate whether
/// the article body, editor name, or edit comment may contain harmful data.
///
/// # Examples
///
/// ```
/// use wme_models::Visibility;
///
/// let visibility = Visibility {
///     text: true,
///     editor: false,
///     comment: false,
/// };
///
/// // When text=false, the article content is hidden
/// // When editor=false, the editor name is hidden
/// // When comment=false, the edit summary is hidden
/// ```
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
pub struct Visibility {
    /// Is article text visible?
    pub text: bool,
    /// Is editor name visible?
    pub editor: bool,
    /// Is edit comment visible?
    pub comment: bool,
}

/// Project reference (simplified, used in article responses).
///
/// This is a lightweight reference to the project an article belongs to.
/// For full project metadata, see [`crate::metadata::ProjectInfo`].
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
pub struct ProjectRef {
    /// Project identifier (e.g., "enwiki")
    pub identifier: String,
    /// Project URL
    pub url: Option<String>,
}

/// Complete article from Enterprise API.
///
/// This is the primary data structure returned by all Enterprise APIs.
/// The same schema is used across On-demand, Snapshot, and Realtime endpoints.
///
/// # Example
///
/// ```
/// use wme_models::Article;
/// use serde_json;
///
/// let json = r#"{
///     "name": "Squirrel",
///     "identifier": 28492,
///     "url": "https://en.wikipedia.org/wiki/Squirrel",
///     "date_created": "2001-01-15T00:00:00Z",
///     "date_modified": "2024-01-15T12:00:00Z",
///     "in_language": {"identifier": "en", "name": "English"},
///     "is_part_of": {"identifier": "enwiki"},
///     "namespace": {"identifier": 0, "name": ""},
///     "license": [{"name": "CC BY-SA 4.0", "url": "https://creativecommons.org/licenses/by-sa/4.0/"}],
///     "version": {
///         "identifier": 1182847293,
///         "editor": {"identifier": 12345, "name": "SomeUser"}
///     }
/// }"#;
///
/// let article: Article = serde_json::from_str(json).unwrap();
/// assert_eq!(article.name, "Squirrel");
/// assert_eq!(article.identifier, 28492);
/// ```
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
pub struct Article {
    /// Article ID (MediaWiki page ID)
    pub identifier: u64,
    /// Article name/title
    pub name: String,
    /// Article URL
    pub url: String,
    /// Article abstract/summary
    #[serde(rename = "abstract")]
    pub abstract_text: Option<String>,
    /// Short description (e.g., "Family of rodents")
    pub description: Option<String>,
    /// Last modification timestamp
    pub date_modified: DateTime<Utc>,
    /// Before-last modification timestamp
    pub date_previously_modified: Option<DateTime<Utc>>,
    /// Language information
    pub in_language: Language,
    /// Project this article belongs to (simplified reference)
    pub is_part_of: ProjectRef,
    /// Namespace information
    pub namespace: Option<Namespace>,
    /// Main Wikidata entity (primary topic)
    pub main_entity: Option<WikidataEntity>,
    /// Additional Wikidata entities used
    pub additional_entities: Option<Vec<WikidataEntityUsage>>,
    /// Categories this article belongs to
    pub categories: Option<Vec<Category>>,
    /// Templates used in this article
    pub templates: Option<Vec<Template>>,
    /// Redirects to this article (alternative names)
    pub redirects: Option<Vec<Redirect>>,
    /// Current version information with credibility signals
    pub version: Version,
    /// Previous version information
    #[serde(default)]
    pub previous_version: OptionalPreviousVersion,
    /// Number of editors watching this page
    pub watchers_count: Option<u64>,
    /// Protection settings (edit/move restrictions)
    pub protection: Option<Vec<Protection>>,
    /// Visibility flags (for visibility-change events)
    pub visibility: Option<Visibility>,
    /// Main image for the article
    pub image: Option<Image>,
    /// License(s) for this article (usually CC-BY-SA)
    pub license: Vec<License>,
    /// Article body content (HTML and wikitext)
    pub article_body: Option<ArticleBody>,
    /// Event metadata (present in Realtime API responses)
    pub event: Option<EventMetadata>,
    /// Has parts - structured content sections (when using fields filter)
    pub has_parts: Option<Vec<Section>>,
}

/// Structured Contents (BETA) - Article with parsed content.
///
/// This type extends [`Article`] with fully parsed content including infoboxes,
/// sections, and tables. Available through the Structured Contents BETA endpoint.
///
/// # Accessing Content
///
/// Use the convenience methods to access parsed content:
///
/// ```rust,ignore
/// use wme_models::StructuredArticle;
///
/// // Get infobox by name
/// if let Some(infobox) = article.infobox("Automatic taxobox") {
///     // Process infobox fields
/// }
///
/// // Get section by name
/// if let Some(section) = article.section("Taxonomy") {
///     // Process section content
/// }
/// ```
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
pub struct StructuredArticle {
    /// Base article fields (flattened)
    #[serde(flatten)]
    pub base: Article,
    /// Creation timestamp (first revision) - only in structured contents
    pub date_created: DateTime<Utc>,
    /// Parsed infoboxes
    pub infoboxes: Vec<Infobox>,
    /// Parsed sections
    pub sections: Vec<Section>,
    /// Tables (single object in structured contents)
    pub tables: Table,
    /// References/citations (single object in structured contents)
    pub references: Reference,
}

impl StructuredArticle {
    /// Get infobox by name.
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use wme_models::StructuredArticle;
    ///
    /// if let Some(infobox) = article.infobox("Automatic taxobox") {
    ///     println!("Found infobox: {:?}", infobox.name);
    /// }
    /// ```
    pub fn infobox(&self, name: &str) -> Option<&Infobox> {
        self.infoboxes
            .iter()
            .find(|i| i.name.as_ref().map(|n| n == name).unwrap_or(false))
    }

    /// Get section by name.
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use wme_models::StructuredArticle;
    ///
    /// if let Some(section) = article.section("References") {
    ///     println!("Section has {} parts", section.has_parts.as_ref().map(|p| p.len()).unwrap_or(0));
    /// }
    /// ```
    pub fn section(&self, name: &str) -> Option<&Section> {
        self.sections
            .iter()
            .find(|s| s.name.as_ref().map(|n| n == name).unwrap_or(false))
    }

    /// Get table by identifier.
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use wme_models::StructuredArticle;
    ///
    /// if let Some(table) = article.table("demographics_table1") {
    ///     println!("Table has {} rows", table.rows.len());
    /// }
    /// ```
    pub fn table(&self, identifier: &str) -> Option<&Table> {
        if self.tables.identifier == identifier {
            Some(&self.tables)
        } else {
            None
        }
    }
}

impl std::ops::Deref for StructuredArticle {
    type Target = Article;

    fn deref(&self) -> &Self::Target {
        &self.base
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::version::{ArticleSize, Editor};
    use chrono::Utc;

    fn create_test_language() -> Language {
        Language {
            identifier: Some("en".to_string()),
            name: Some("English".to_string()),
            alternate_name: None,
            direction: Some("ltr".to_string()),
        }
    }

    fn create_test_namespace() -> Namespace {
        Namespace {
            identifier: 0,
            name: Some("".to_string()),
            description: Some("Main namespace".to_string()),
        }
    }

    fn create_test_project_ref() -> ProjectRef {
        ProjectRef {
            identifier: "enwiki".to_string(),
            url: Some("https://en.wikipedia.org".to_string()),
        }
    }

    fn create_test_version() -> Version {
        Version {
            identifier: 1182847293,
            editor: Some(Editor {
                identifier: Some(12345),
                name: Some("TestUser".to_string()),
                is_bot: Some(false),
                is_anonymous: Some(false),
                date_started: Some(Utc::now()),
                edit_count: Some(1000),
                groups: Some(vec!["user".to_string()]),
                is_admin: Some(false),
                is_patroller: Some(false),
                has_advanced_rights: Some(false),
            }),
            comment: Some("Test edit".to_string()),
            tags: Some(vec!["mobile edit".to_string()]),
            has_tag_needs_citation: Some(false),
            is_minor_edit: Some(false),
            is_flagged_stable: Some(true),
            is_breaking_news: Some(false),
            noindex: Some(false),
            number_of_characters: Some(5000),
            size: Some(ArticleSize {
                value: 15000,
                unit_text: "B".to_string(),
            }),
            maintenance_tags: None,
            scores: None,
        }
    }

    fn create_test_article() -> Article {
        Article {
            identifier: 28492,
            name: "Squirrel".to_string(),
            url: "https://en.wikipedia.org/wiki/Squirrel".to_string(),
            abstract_text: Some("Squirrels are members of the family Sciuridae...".to_string()),
            description: Some("Family of rodents".to_string()),
            date_modified: Utc::now(),
            date_previously_modified: None,
            in_language: create_test_language(),
            is_part_of: create_test_project_ref(),
            namespace: Some(create_test_namespace()),
            main_entity: None,
            additional_entities: None,
            categories: None,
            templates: None,
            redirects: None,
            version: create_test_version(),
            previous_version: OptionalPreviousVersion(None),
            watchers_count: Some(42),
            protection: None,
            visibility: None,
            image: None,
            license: vec![],
            article_body: None,
            event: None,
            has_parts: None,
        }
    }

    #[test]
    fn test_article_creation() {
        let article = create_test_article();
        assert_eq!(article.identifier, 28492);
        assert_eq!(article.name, "Squirrel");
        assert!(article.abstract_text.is_some());
    }

    #[test]
    fn test_project_ref_creation() {
        let project = ProjectRef {
            identifier: "enwiki".to_string(),
            url: Some("https://en.wikipedia.org".to_string()),
        };
        assert_eq!(project.identifier, "enwiki");
        assert!(project.url.is_some());
    }

    #[test]
    fn test_visibility_creation() {
        let visibility = Visibility {
            text: true,
            editor: false,
            comment: false,
        };
        assert!(visibility.text);
        assert!(!visibility.editor);
        assert!(!visibility.comment);
    }

    #[test]
    fn test_version_comparison_for_dedup() {
        let article1 = create_test_article();
        let article2 = Article {
            identifier: 28492,
            name: "Squirrel".to_string(),
            url: "https://en.wikipedia.org/wiki/Squirrel".to_string(),
            abstract_text: None,
            description: None,
            date_modified: Utc::now(),
            date_previously_modified: None,
            in_language: create_test_language(),
            is_part_of: create_test_project_ref(),
            namespace: Some(create_test_namespace()),
            main_entity: None,
            additional_entities: None,
            categories: None,
            templates: None,
            redirects: None,
            version: Version {
                identifier: 1182847294, // Higher version
                editor: create_test_version().editor,
                comment: None,
                tags: None,
                has_tag_needs_citation: None,
                is_minor_edit: None,
                is_flagged_stable: None,
                is_breaking_news: None,
                noindex: None,
                number_of_characters: None,
                size: None,
                maintenance_tags: None,
                scores: None,
            },
            previous_version: OptionalPreviousVersion(None),
            watchers_count: None,
            protection: None,
            visibility: None,
            image: None,
            license: vec![],
            article_body: None,
            event: None,
            has_parts: None,
        };

        // When deduplicating, keep the one with higher version.identifier
        assert!(article2.version.identifier > article1.version.identifier);
    }
}