path: root/src/raeapi.rs

//! Main source: rae-api.com, which serves the DLE content as JSON.
//!
//! It carries less than the DLE page (no conjugation) and allows 10 requests
//! per minute, but its format is stable and, unlike dle.rae.es, it answers
//! automated clients.

use anyhow::{Context, Result};
use serde::Deserialize;

use crate::client::{percent_encode, Http};
use crate::model::{Abbr, Entry, Sense};

const BASE: &str = "https://rae-api.com/api";

#[derive(Deserialize)]
struct Response {
    data: Option<Data>,
}

#[derive(Deserialize)]
struct Data {
    word: String,
    #[serde(default)]
    meanings: Vec<Meaning>,
}

#[derive(Deserialize)]
struct Meaning {
    origin: Option<Origin>,
    #[serde(default)]
    senses: Vec<ApiSense>,
}

#[derive(Deserialize)]
struct Origin {
    raw: Option<String>,
}

#[derive(Deserialize)]
struct ApiSense {
    /// The sense as the dictionary prints it, marks included:
    /// `"1. intr. Emitir palabras."`
    raw: Option<String>,
    meaning_number: Option<u32>,
    description: Option<String>,
    category: Option<String>,
    gender: Option<String>,
    usage: Option<String>,
    #[serde(default)]
    examples: Vec<String>,
    synonyms: Option<Vec<String>>,
    antonyms: Option<Vec<String>>,
}

/// Looks up a word. `Ok(None)` if the API says it does not exist.
pub fn lookup(http: &Http, word: &str) -> Result<Option<Entry>> {
    let url = format!("{BASE}/words/{}", percent_encode(word));
    let (status, body) = http.get(&url, crate::client::CLIENT_UA)?;
    if status == 404 {
        return Ok(None);
    }
    if status == 429 {
        anyhow::bail!(
            "rae-api limita a 10 consultas por minuto y se alcanzó el tope; \
             espera un momento (lo ya consultado sigue disponible en la caché)"
        );
    }
    if status != 200 {
        anyhow::bail!("rae-api respondió {status}");
    }
    let res: Response =
        serde_json::from_str(&body).context("rae-api devolvió un JSON inesperado")?;
    Ok(res.data.map(into_entry))
}

/// The word of the day published by the RAE.
pub fn word_of_the_day(http: &Http) -> Result<String> {
    single_word(http, &format!("{BASE}/daily"))
}

/// A random word from the dictionary.
pub fn random_word(http: &Http) -> Result<String> {
    single_word(http, &format!("{BASE}/random"))
}

fn single_word(http: &Http, url: &str) -> Result<String> {
    #[derive(Deserialize)]
    struct Wrapper {
        data: Inner,
    }
    #[derive(Deserialize)]
    struct Inner {
        word: String,
    }
    let (status, body) = http.get(url, crate::client::CLIENT_UA)?;
    if status == 429 {
        anyhow::bail!("rae-api limita a 10 consultas por minuto y se alcanzó el tope");
    }
    if status != 200 {
        anyhow::bail!("rae-api respondió {status}");
    }
    let w: Wrapper = serde_json::from_str(&body).context("rae-api devolvió un JSON inesperado")?;
    Ok(w.data.word)
}

fn into_entry(d: Data) -> Entry {
    let etymology = d
        .meanings
        .iter()
        .find_map(|m| m.origin.as_ref().and_then(|o| o.raw.clone()))
        .filter(|s| !s.trim().is_empty());
    let senses = d
        .meanings
        .iter()
        .flat_map(|m| m.senses.iter())
        .map(into_sense)
        .collect();
    Entry {
        word: d.word,
        etymology,
        senses,
        locutions: vec![],
        conjugation: None,
        source: "rae-api".into(),
    }
}

fn into_sense(s: &ApiSense) -> Sense {
    // The API labels in English; translate to the DLE abbreviations so the
    // output looks the same whatever the source.
    let description = s.description.as_deref().unwrap_or_default().trim();

    // The `raw` field holds the sense as printed, with the exact dictionary
    // marks («intr.», «p. us.»). That beats rebuilding them from the English
    // labels, which are coarser: they say «verb» where the dictionary tells
    // transitive from intransitive.
    if let Some(marks) = s.raw.as_deref().and_then(|r| printed_marks(r, description)) {
        let grammar = expand_marks(&marks);
        return Sense {
            number: s.meaning_number.map(|n| n.to_string()),
            grammar,
            text: close_sentence(&format!("{marks} {description}")),
            examples: s.examples.clone(),
            synonyms: s.synonyms.clone().unwrap_or_default(),
            antonyms: s.antonyms.clone().unwrap_or_default(),
        };
    }

    let mut grammar = Vec::new();
    // The dictionary writes «f.», not «s. f.»: the gender mark already says
    // the word is a noun, so the category is redundant.
    let gendered = s.gender.as_deref().is_some_and(|g| !g.is_empty());
    let category = match s.category.as_deref() {
        Some("noun") if gendered => None,
        other => other.map(str::to_string),
    };
    for (value, table) in [
        (&category, CATEGORIES),
        (&s.gender, GENDERS),
        (&s.usage, USAGES),
    ] {
        let Some(v) = value.as_deref().filter(|v| !v.is_empty()) else {
            continue;
        };
        if let Some((short, long)) = table
            .iter()
            .find(|(k, _, _)| *k == v)
            .map(|(_, s, l)| (*s, *l))
        {
            grammar.push(Abbr {
                short: short.into(),
                long: long.into(),
            });
        }
    }
    // The API returns the bare definition, without the marks or the final
    // dot the dictionary prints. Put them back so the output reads the same
    // whatever the source.
    let text = printed_form(&grammar, s.description.as_deref().unwrap_or_default());

    Sense {
        number: s.meaning_number.map(|n| n.to_string()),
        grammar,
        text,
        examples: s.examples.clone(),
        synonyms: s.synonyms.clone().unwrap_or_default(),
        antonyms: s.antonyms.clone().unwrap_or_default(),
    }
}

/// Builds the definition as the dictionary prints it: grammar marks in front
/// and a dot at the end.
fn printed_form(grammar: &[Abbr], description: &str) -> String {
    let description = description.trim();
    if description.is_empty() {
        return String::new();
    }
    let marks: Vec<&str> = grammar.iter().map(|a| a.short.as_str()).collect();
    let joined = if marks.is_empty() {
        description.to_string()
    } else {
        format!("{} {description}", marks.join(" "))
    };
    close_sentence(&joined)
}

/// Adds the final dot unless the definition already ends closed.
fn close_sentence(text: &str) -> String {
    let text = text.trim();
    if text.is_empty() {
        return String::new();
    }
    match text.chars().next_back() {
        Some(c) if ".!?…".contains(c) => text.to_string(),
        _ => format!("{text}."),
    }
}

/// Cuts the marks out of the printed text: whatever sits between the sense
/// number and the start of the definition.
fn printed_marks(raw: &str, description: &str) -> Option<String> {
    if description.is_empty() {
        return None;
    }
    let head = &raw[..raw.find(description)?];
    let head = head.trim_start_matches(|c: char| c.is_ascii_digit());
    let marks = head.trim_start().strip_prefix('.').unwrap_or(head).trim();
    (!marks.is_empty()).then(|| marks.to_string())
}

/// Expands dictionary abbreviations. Tries the longest first, because
/// «p. us.» starts like a one-letter abbreviation.
fn expand_marks(marks: &str) -> Vec<Abbr> {
    let mut out: Vec<Abbr> = Vec::new();
    let mut rest = marks.trim();
    while !rest.is_empty() {
        match ABBREVIATIONS