Formato standard

export interface TranslationBookChapter {
    /**
     * Informazioni sulla traduzione del capitolo del libro.
     */
    translation: Translation;

    /**
     * Informazioni sul capitolo del libro.
     */
    book: TranslationBook;

    /**
     * Il link al capitolo corrente.
     */
    thisChapterLink: string;

    /**
     * I link alle diverse versioni audio del capitolo.
     */
    thisChapterAudioLinks: TranslationBookChapterAudioLinks;

    /**
     * I link ai tempi audio per le diverse versioni audio del capitolo.
     * Ciascun link rimanda al file con i tempi audio per quel lettore - vedi "Ottieni i tempi audio per un capitolo" qui sotto.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsLinks;

    /**
     * Il link al capitolo successivo.
     * Nullo se questo è l'ultimo capitolo della traduzione.
     */
    nextChapterApiLink: string | null;

    /**
     * I link alle diverse versioni audio per il prossimo capitolo.
     * Nullo se questo è l'ultimo capitolo della traduzione.
     */
    nextChapterAudioLinks: TranslationBookChapterAudioLinks | null;

    /**
     * Di seguito i link ai tempi audio per le diverse versioni audio del capitolo successivo.
     * Nullo se questo è l'ultimo capitolo della traduzione.
     */
    nextChapterAudioTimings: TranslationBookChapterAudioTimingsLinks | null;

    /**
     * Il link al capitolo precedente.
     * Nullo se questo è il primo capitolo della traduzione.
     */
    previousChapterApiLink: string | null;

    /**
     * I link alle diverse versioni audio del capitolo precedente.
     * Nullo se questo è il primo capitolo della traduzione.
     */
    previousChapterAudioLinks: TranslationBookChapterAudioLinks | null;

    /**
     * I link ai timestamp audio per le diverse versioni audio del capitolo precedente.
     * Nullo se questo è il primo capitolo della traduzione.
     */
    previousChapterAudioTimings: TranslationBookChapterAudioTimingsLinks | null;

    /**
     * Il link alle annotazioni a livello di parola per il capitolo.
     * Omesso se il capitolo non presenta annotazioni a livello di singola parola.
     */
    thisChapterWordsLink?: string;

    /**
     * Il link alle annotazioni a livello di parola per il capitolo successivo.
     * Omesso se questo è l'ultimo capitolo della traduzione, o se il capitolo successivo non presenta annotazioni a livello di parola.
     */
    nextChapterWordsLink?: string;

    /**
     * Il link alle annotazioni a livello di parola del capitolo precedente.
     * Omesso se si tratta del primo capitolo della traduzione, oppure se il capitolo precedente non presenta annotazioni a livello di parola.
     */
    previousChapterWordsLink?: string;

    /**
     * Il numero di versetti contenuti nel capitolo.
     */
    numberOfVerses: number;

    /**
     * Ecco il link alla versione semplificata di questo capitolo.
     * Omesso se non sono disponibili capitoli semplificati.
     */
    simpleChapterApiLink?: string;

    /**
     * Le informazioni relative al capitolo.
     */
    chapter: ChapterData;
}

interface ChapterData {
    /**
     * Il numero del capitolo.
     */
    number: number;

    /**
     * Il contenuto del capitolo.
     */
    content: ChapterContent[];

    /**
     * Elenco delle note a piè di pagina del capitolo.
     */
    footnotes: ChapterFootnote[];
}

/**
 * Un tipo di unione che rappresenta un singolo elemento del contenuto di un capitolo.
 * Il contenuto di un capitolo può essere uno dei seguenti:
 * - Un titolo.
 * - Un'interruzione di riga.
 * - Un verso.
 * - Sottotitoli in ebraico.
 */
type ChapterContent = ChapterHeading | ChapterLineBreak | ChapterVerse | ChapterHebrewSubtitle;

/**
 * Un titolo all'interno di un capitolo.
 */
interface ChapterHeading {
    /**
     * Indica che il contenuto rappresenta un'intestazione.
     */
    type: 'heading';

    /**
     * Il contenuto dell'intestazione.
     * Se l'array contiene più stringhe, queste devono essere concatenate separandole con uno spazio.
     */
    content: string[];
}

/**
 * Un'interruzione di riga in un capitolo.
 */
interface ChapterLineBreak {
    /**
     * Indica che il contenuto rappresenta un'interruzione di riga.
     */
    type: 'line_break';
}

/**
 * Un sottotitolo in ebraico in un capitolo.
 * Questi elementi vengono spesso inclusi come contenuti informativi presenti nei manoscritti originali.
 * Ad esempio, il Salmo 49 ha il sottotitolo ebraico "Al maestro del coro. Salmo dei figli di Core".
 */
interface ChapterHebrewSubtitle {
    /**
     * Indica che il contenuto rappresenta un sottotitolo in ebraico.
     */
    type: 'hebrew_subtitle';

    /**
     * L'elenco dei contenuti contenuti nel sottotitolo.
     * Ciascun elemento dell'elenco potrebbe essere una stringa, un testo formattato o un riferimento a una nota a piè di pagina.
     */
    content: (string | FormattedText | VerseFootnoteReference)[];
}

/**
 * Un versetto in un capitolo.
 */
interface ChapterVerse {
    /**
     * Indica che il contenuto è un verso.
     */
    type: 'verse';

    /**
     * Il numero del versetto.
     */
    number: number;

    /**
     * L'elenco dei contenuti del versetto.
     * Ciascun elemento dell'elenco potrebbe essere una stringa, un testo formattato o un riferimento a una nota a piè di pagina.
     */
    content: (string | FormattedText | InlineHeading | InlineLineBreak | VerseFootnoteReference)[];
}

/**
 * Testo formattato. Ovvero, testo formattato in un modo particolare.
 */
interface FormattedText {
    /**
     * Il testo formattato.
     */
    text: string;

    /**
     * Se il testo rappresenta una poesia.
     * Il numero indica il livello di rientranza.
     *
     * Comune nei Salmi.
     */
    poem?: number;

    /**
     * Se il testo rappresenti le parole di Gesù.
     */
    wordsOfJesus?: boolean;
}

/**
 * Definisce un'interfaccia che rappresenta un'intestazione incorporata in un verso.
 */
interface InlineHeading {
    /**
     * Il testo dell'intestazione.
     */
    heading: string;
}

/**
 * Definisce un'interfaccia che rappresenta un'interruzione di riga incorporata in un verso.
 */
interface InlineLineBreak {
    lineBreak: true;
}


/**
 * Una nota a piè di pagina in un verso o un sottotitolo in ebraico.
 */
interface VerseFootnoteReference {
    /**
     * L'ID della nota.
     */
    noteId: number;
}

/**
 * Informazioni su una nota a piè di pagina.
 */
interface ChapterFootnote {
    /**
     * L'ID della nota a cui si fa riferimento.
     */
    noteId: number;

    /**
     * Il testo della nota a piè di pagina.
     */
    text: string;

    /**
     * Il riferimento al verso per la nota a piè di pagina.
     */
    reference?: {
        chapter: number;
        verse: number;
    };

    /**
     * Il chiamante da utilizzare per la nota a piè di pagina.
     * Per le note a piè di pagina, il "richiamante" è il carattere utilizzato nel testo per fare riferimento alla nota a piè di pagina.
     *
     * Ad esempio, nel testo:
     * Ciao (a) Mondo
     *
     * ---- (a) Questa è una nota a piè di pagina.
     *
     * La "(a)" indica chi effettua la chiamata.
     *
     * Se "+", il chiamante dovrebbe essere generato automaticamente.
     * Se nullo, il chiamante deve essere vuoto.
     * Se si tratta di una stringa, il chiamante dovrebbe essere quella stringa.
     */
    caller: '+' | string | null;
}

/**
 * I link audio per un capitolo del libro.
 */
interface TranslationBookChapterAudioLinks {
    /**
     * Il testo del capitolo e il link URL al file audio.
     */
    [reader: string]: string;
}

/**
 * I link relativi alla temporizzazione audio di un capitolo del libro.
 */
interface TranslationBookChapterAudioTimingsLinks {
    /**
     * Il lettore per il capitolo e il collegamento API al file delle tempistiche audio per quel lettore.
     */
    [reader: string]: string;
}

/**
 * Definisce la durata dell'audio per un capitolo del libro, per un singolo lettore.
 * Corrisponde all'endpoint /api/{translation}/{book}/{chapter}.{reader}.audioTimings.json.
 */
export interface TranslationBookChapterAudioTimings {
    /**
     * L'ID della traduzione.
     */
    translationId: string;

    /**
     * L'ID del libro.
     */
    bookId: string;

    /**
     * Il numero del capitolo.
     */
    chapterNumber: number;

    /**
     * L'ID del lettore a cui sono destinati questi orari.
     */
    reader: string;

    /**
     * Ecco il link al file audio a cui si riferiscono queste indicazioni temporali.
     */
    audioLink: string;

    /**
     * Il link alle informazioni relative a questo capitolo.
     */
    thisChapterLink: string;

    /**
     * Ecco il link alle informazioni per il capitolo successivo.
     * Nullo se questo è l'ultimo capitolo della traduzione.
     */
    nextChapterLink: string | null;

    /**
     * Il link alle informazioni relative al capitolo precedente.
     * Nullo se questo è il primo capitolo della traduzione.
     */
    previousChapterLink: string | null;

    /**
     * Il link al file con le tempistiche audio.
     */
    thisChapterAudioTimingsLink: string;

    /**
     * Ecco il link con gli orari del prossimo capitolo, per lo stesso lettore.
     * Nullo se questo è l'ultimo capitolo della traduzione.
     */
    nextChapterAudioTimingsLink: string | null;

    /**
     * Il link ai tempi relativi al capitolo precedente, per lo stesso lettore.
     * Nullo se questo è il primo capitolo della traduzione.
     */
    previousChapterAudioTimingsLink: string | null;

    /**
     * Gli istanti in secondi in cui inizia ogni strofa, in ordine.
     * Il primo numero (indice 0) indica il punto della registrazione in cui inizia la prima strofa.
     */
    verses: number[];
}

export interface TranslationBookChapterWords {
    /**
     * L'ID della traduzione.
     */
    translationId: string;

    /**
     * L'ID del libro.
     */
    bookId: string;

    /**
     * Il numero del capitolo.
     */
    chapterNumber: number;

    /**
     * Il link alle informazioni relative a questo capitolo.
     */
    thisChapterLink: string;

    /**
     * Ecco il link alle informazioni per il capitolo successivo.
     * Nullo se questo è l'ultimo capitolo della traduzione.
     */
    nextChapterLink: string | null;

    /**
     * Il link alle informazioni relative al capitolo precedente.
     * Nullo se questo è il primo capitolo della traduzione.
     */
    previousChapterLink: string | null;

    /**
     * Il link a questo file di testo.
     */
    thisChapterWordsLink: string;

    /**
     * Ecco il link al testo del prossimo capitolo.
     * Valore nullo se questo è l'ultimo capitolo della traduzione, oppure se il capitolo successivo non presenta annotazioni a livello di parola.
     */
    nextChapterWordsLink: string | null;

    /**
     * Il link al testo del capitolo precedente.
     * Valore nullo se si tratta del primo capitolo della traduzione o se il capitolo precedente non presenta annotazioni a livello di parola.
     */
    previousChapterWordsLink: string | null;

    /**
     * Il testo annotato per ogni versetto del capitolo, con indicazione del numero del versetto.
     * Ogni elenco segue l'ordine in cui le parole compaiono nel versetto.
     */
    verses: {
        [verseNumber: string]: ChapterWord[];
    };
}

interface ChapterWord {
    /**
     * L'indice dell'elemento nell'array di contenuti del verso a cui si applica l'annotazione.
     */
    contentIndex: number;

    /**
     * L'indice del primo carattere della parola annotata nel testo dell'elemento di contenuto.
     */
    start: number;

    /**
     * L'indice che segue l'ultimo carattere della parola annotata nel testo dell'elemento di contenuto.
     * Ovvero, text.slice(start, end) è la parola annotata.
     */
    end: number;

    /**
     * Il/I numero/i di Strong per la parola.
     * Omesso se la traduzione forniva solo altre annotazioni per la parola.
     */
    strongs?: string[];

    /**
     * La forma del termine presente nel dizionario (citazione).
     * Omesso se la traduzione non lo prevedeva.
     */
    lemma?: string;

    /**
     * Il codice di analisi morfologica per la parola.
     * Omesso se la traduzione non lo prevedeva.
     */
    morph?: string;

    /**
     * Il puntatore alla parola nel testo sorgente, nel formato <sourceName> : <location> .
     * Omesso se la traduzione non lo prevedeva.
     */
    srcloc?: string;

    /**
     * Quale occorrenza della parola di origine è questa parola. 1-based.
     * Omesso se la traduzione non lo prevedeva.
     */
    occurrence?: number;

    /**
     * Il numero totale di volte in cui ricorre la parola di origine.
     * Omesso se la traduzione non lo prevedeva.
     */
    occurrences?: number;
}

/**
 * Definisce i dati completi per il download della traduzione.
 * Corrisponde all'endpoint /api/:translationId/complete.json.
 */
export interface TranslationComplete {
    /**
     * I metadati di traduzione.
     */
    translation: Translation;

    /**
     * L'elenco completo dei libri con tutti i loro capitoli.
     */
    books: TranslationCompleteBook[];
}

/**
 * Un libro nella sua traduzione completa da scaricare.
 */
export interface TranslationCompleteBook {
    /**
     * L'ID del libro.
     */
    id: string;

    /**
     * Il titolo del libro tratto dalla traduzione.
     */
    name: string;

    /**
     * Il nome comune del libro.
     */
    commonName: string;

    /**
     * Il titolo del libro.
     */
    title: string | null;

    /**
     * L'ordine del libro.
     */
    order: number;

    /**
     * Il numero di capitoli del libro.
     */
    numberOfChapters: number;

    /**
     * Il numero totale di versi presenti nel libro.
     */
    totalNumberOfVerses: number;

    /**
     * Se il libro sia apocrifo o meno.
     */
    isApocryphal?: boolean;

    /**
     * L'elenco completo dei capitoli con tutti i contenuti.
     */
    chapters: TranslationCompleteChapter[];
}

/**
 * Un capitolo nella traduzione completa scaricabile.
 */
export interface TranslationCompleteChapter {
    /**
     * Il numero di versetti contenuti nel capitolo.
     */
    numberOfVerses: number;

    /**
     * I link alle diverse versioni audio del capitolo.
     */
    thisChapterAudioLinks: TranslationBookChapterAudioLinks;

    /**
     * Le tempistiche audio (tempi di inizio per strofa, in secondi) per le diverse versioni audio del capitolo.
     *
     * A differenza del valore `thisChapterAudioTimings` presente nell'endpoint del singolo capitolo (che rimanda a "Ottieni i tempi audio per un capitolo" qui sotto), questo contiene i tempi stessi, poiché lo scopo del download della traduzione completa è quello di avere tutto in un unico file.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsMap;

    /**
     * Il link alle annotazioni a livello di parola per il capitolo.
     * Omesso se il capitolo non presenta annotazioni a livello di singola parola.
     */
    thisChapterWordsLink?: string;

    /**
     * Le informazioni relative al capitolo.
     */
    chapter: ChapterData;
}

/**
 * La temporizzazione audio di un capitolo del libro, incorporata direttamente anziché tramite un link.
 * Associa l'ID di un lettore all'elenco degli istanti (in secondi) in cui inizia ciascun verso, nell'ordine dei versi.
 */
interface TranslationBookChapterAudioTimingsMap {
    [reader: string]: number[];
}