Formato estándar

export interface TranslationBookChapter {
    /**
     * Información sobre la traducción del capítulo del libro.
     */
    translation: Translation;

    /**
     * La información del libro correspondiente al capítulo del libro.
     */
    book: TranslationBook;

    /**
     * El enlace al capítulo actual.
     */
    thisChapterLink: string;

    /**
     * Enlaces a diferentes versiones de audio para el capítulo.
     */
    thisChapterAudioLinks: TranslationBookChapterAudioLinks;

    /**
     * Enlaces a los tiempos de audio para las diferentes versiones de audio del capítulo.
     * Cada enlace apunta al archivo de sincronización de audio para ese lector; consulte "Obtener la sincronización de audio para un capítulo" a continuación.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsLinks;

    /**
     * El enlace al siguiente capítulo.
     * Nulo si este es el último capítulo de la traducción.
     */
    nextChapterApiLink: string | null;

    /**
     * Enlaces a las diferentes versiones de audio del próximo capítulo.
     * Nulo si este es el último capítulo de la traducción.
     */
    nextChapterAudioLinks: TranslationBookChapterAudioLinks | null;

    /**
     * Enlaces a la sincronización del audio para las diferentes versiones de audio del próximo capítulo.
     * Nulo si este es el último capítulo de la traducción.
     */
    nextChapterAudioTimings: TranslationBookChapterAudioTimingsLinks | null;

    /**
     * El enlace al capítulo anterior.
     * Nulo si este es el primer capítulo de la traducción.
     */
    previousChapterApiLink: string | null;

    /**
     * Enlaces a diferentes versiones de audio del capítulo anterior.
     * Nulo si este es el primer capítulo de la traducción.
     */
    previousChapterAudioLinks: TranslationBookChapterAudioLinks | null;

    /**
     * Enlaces a la sincronización del audio para las diferentes versiones de audio del capítulo anterior.
     * Nulo si este es el primer capítulo de la traducción.
     */
    previousChapterAudioTimings: TranslationBookChapterAudioTimingsLinks | null;

    /**
     * Enlace a las anotaciones a nivel de palabra del capítulo.
     * Se omite si el capítulo no tiene anotaciones a nivel de palabra.
     */
    thisChapterWordsLink?: string;

    /**
     * Enlace a las anotaciones a nivel de palabra del próximo capítulo.
     * Se omite si este es el último capítulo de la traducción o si el siguiente capítulo no tiene anotaciones a nivel de palabra.
     */
    nextChapterWordsLink?: string;

    /**
     * Enlace a las anotaciones a nivel de palabra del capítulo anterior.
     * Se omite si este es el primer capítulo de la traducción o si el capítulo anterior no tiene anotaciones a nivel de palabra.
     */
    previousChapterWordsLink?: string;

    /**
     * El número de versículos que contiene el capítulo.
     */
    numberOfVerses: number;

    /**
     * Enlace a la versión simplificada de este capítulo.
     * Se omite si no hay capítulos simplificados disponibles.
     */
    simpleChapterApiLink?: string;

    /**
     * La información del capítulo.
     */
    chapter: ChapterData;
}

interface ChapterData {
    /**
     * El número del capítulo.
     */
    number: number;

    /**
     * El contenido del capítulo.
     */
    content: ChapterContent[];

    /**
     * Lista de notas a pie de página del capítulo.
     */
    footnotes: ChapterFootnote[];
}

/**
 * Un tipo de unión que representa una sola pieza de contenido de un capítulo.
 * Un fragmento del contenido de un capítulo puede ser una de las siguientes cosas:
 * - Un encabezado.
 * - Un salto de línea.
 * - Un verso.
 * - Un subtítulo en hebreo.
 */
type ChapterContent = ChapterHeading | ChapterLineBreak | ChapterVerse | ChapterHebrewSubtitle;

/**
 * Un encabezado en un capítulo.
 */
interface ChapterHeading {
    /**
     * Indica que el contenido representa un encabezado.
     */
    type: 'heading';

    /**
     * El contenido del encabezado.
     * Si el array incluye varias cadenas, deben concatenarse con un espacio.
     */
    content: string[];
}

/**
 * Un salto de línea en un capítulo.
 */
interface ChapterLineBreak {
    /**
     * Indica que el contenido representa un salto de línea.
     */
    type: 'line_break';
}

/**
 * Un subtítulo en hebreo en un capítulo.
 * Estos elementos se utilizan a menudo como contenido informativo que aparecía en los manuscritos originales.
 * Por ejemplo, el Salmo 49 tiene el subtítulo en hebreo "Al director del coro. Salmo de los hijos de Coré".
 */
interface ChapterHebrewSubtitle {
    /**
     * Indica que el contenido corresponde a un subtítulo en hebreo.
     */
    type: 'hebrew_subtitle';

    /**
     * La lista de contenido que aparece en el subtítulo.
     * Cada elemento de la lista podría ser una cadena de texto, un texto con formato o una referencia a una nota al pie.
     */
    content: (string | FormattedText | VerseFootnoteReference)[];
}

/**
 * Un versículo en un capítulo.
 */
interface ChapterVerse {
    /**
     * Indica que el contenido es un versículo.
     */
    type: 'verse';

    /**
     * El número del versículo.
     */
    number: number;

    /**
     * La lista de contenido del versículo.
     * Cada elemento de la lista podría ser una cadena de texto, un texto con formato o una referencia a una nota al pie.
     */
    content: (string | FormattedText | InlineHeading | InlineLineBreak | VerseFootnoteReference)[];
}

/**
 * Texto formateado. Es decir, texto que está formateado de una manera particular.
 */
interface FormattedText {
    /**
     * El texto que está formateado.
     */
    text: string;

    /**
     * Si el texto representa un poema.
     * El número indica el nivel de sangría.
     *
     * Común en los Salmos.
     */
    poem?: number;

    /**
     * Si el texto representa las Palabras de Jesús.
     */
    wordsOfJesus?: boolean;
}

/**
 * Define una interfaz que representa un encabezado incrustado en un versículo.
 */
interface InlineHeading {
    /**
     * El texto del encabezado.
     */
    heading: string;
}

/**
 * Define una interfaz que representa un salto de línea insertado en un verso.
 */
interface InlineLineBreak {
    lineBreak: true;
}


/**
 * Una referencia a una nota al pie de página en un versículo o en un subtítulo hebreo.
 */
interface VerseFootnoteReference {
    /**
     * El ID de la nota.
     */
    noteId: number;
}

/**
 * Información sobre una nota al pie.
 */
interface ChapterFootnote {
    /**
     * El ID de la nota a la que se hace referencia.
     */
    noteId: number;

    /**
     * El texto de la nota al pie.
     */
    text: string;

    /**
     * La referencia del versículo para la nota al pie.
     */
    reference?: {
        chapter: number;
        verse: number;
    };

    /**
     * La persona que realizó la llamada que debe utilizarse para la nota al pie.
     * En el caso de las notas al pie, un "indicador" es el carácter que se utiliza en el texto para hacer referencia a la nota al pie.
     *
     * Por ejemplo, en el texto:
     * Hola (a) Mundo
     *
     * ---- (a) Esta es una nota al pie.
     *
     * El "(a)" es quien llama.
     *
     * Si es "+", entonces la persona que realiza la llamada debería generarse automáticamente.
     * Si es nulo, entonces el llamador debe estar vacío.
     * Si es una cadena, entonces quien realiza la llamada debe ser esa cadena.
     */
    caller: '+' | string | null;
}

/**
 * Los enlaces de audio para un capítulo del libro.
 */
interface TranslationBookChapterAudioLinks {
    /**
     * El texto del capítulo y el enlace URL al archivo de audio.
     */
    [reader: string]: string;
}

/**
 * Los enlaces con los tiempos de audio para un capítulo del libro.
 */
interface TranslationBookChapterAudioTimingsLinks {
    /**
     * El lector del capítulo y el enlace API al archivo de sincronización de audio para dicho lector.
     */
    [reader: string]: string;
}

/**
 * Define la duración del audio para un capítulo de un libro, para un solo lector.
 * Se asigna al punto final /api/{translation}/{book}/{chapter}.{reader}.audioTimings.json.
 */
export interface TranslationBookChapterAudioTimings {
    /**
     * El ID de la traducción.
     */
    translationId: string;

    /**
     * La identificación del libro.
     */
    bookId: string;

    /**
     * El número del capítulo.
     */
    chapterNumber: number;

    /**
     * La identificación del lector al que se refieren estos tiempos.
     */
    reader: string;

    /**
     * El enlace al archivo de audio al que corresponden estas indicaciones de tiempo.
     */
    audioLink: string;

    /**
     * Enlace a la información de este capítulo.
     */
    thisChapterLink: string;

    /**
     * Enlace a la información del próximo capítulo.
     * Nulo si este es el último capítulo de la traducción.
     */
    nextChapterLink: string | null;

    /**
     * Enlace a la información del capítulo anterior.
     * Nulo si este es el primer capítulo de la traducción.
     */
    previousChapterLink: string | null;

    /**
     * El enlace a este archivo de tiempos de audio.
     */
    thisChapterAudioTimingsLink: string;

    /**
     * El enlace a los horarios del próximo capítulo, para el mismo lector.
     * Nulo si este es el último capítulo de la traducción.
     */
    nextChapterAudioTimingsLink: string | null;

    /**
     * Enlace a los horarios del capítulo anterior, para el mismo lector.
     * Nulo si este es el primer capítulo de la traducción.
     */
    previousChapterAudioTimingsLink: string | null;

    /**
     * Los tiempos en segundos en los que comienza cada verso, en orden.
     * El primer número (índice 0) indica el momento de la grabación en el que comienza la primera estrofa.
     */
    verses: number[];
}

export interface TranslationBookChapterWords {
    /**
     * El ID de la traducción.
     */
    translationId: string;

    /**
     * La identificación del libro.
     */
    bookId: string;

    /**
     * El número del capítulo.
     */
    chapterNumber: number;

    /**
     * Enlace a la información de este capítulo.
     */
    thisChapterLink: string;

    /**
     * Enlace a la información del próximo capítulo.
     * Nulo si este es el último capítulo de la traducción.
     */
    nextChapterLink: string | null;

    /**
     * Enlace a la información del capítulo anterior.
     * Nulo si este es el primer capítulo de la traducción.
     */
    previousChapterLink: string | null;

    /**
     * El enlace a este archivo de palabras.
     */
    thisChapterWordsLink: string;

    /**
     * El enlace a las palabras del siguiente capítulo.
     * Nulo si este es el último capítulo de la traducción, o si el siguiente capítulo no tiene anotaciones a nivel de palabra.
     */
    nextChapterWordsLink: string | null;

    /**
     * Enlace a las palabras del capítulo anterior.
     * Nulo si este es el primer capítulo de la traducción, o si el capítulo anterior no tiene anotaciones a nivel de palabra.
     */
    previousChapterWordsLink: string | null;

    /**
     * Las palabras anotadas para cada versículo del capítulo, indicadas por el número del versículo.
     * Cada lista está en el orden en que aparecen las palabras en el versículo.
     */
    verses: {
        [verseNumber: string]: ChapterWord[];
    };
}

interface ChapterWord {
    /**
     * El índice del elemento en la matriz de contenido del verso al que se aplica la anotación.
     */
    contentIndex: number;

    /**
     * El índice del primer carácter de la palabra anotada en el texto del elemento de contenido.
     */
    start: number;

    /**
     * El índice que aparece después del último carácter de la palabra anotada en el texto del elemento de contenido.
     * Es decir, text.slice(start, end) es la palabra anotada.
     */
    end: number;

    /**
     * El/los número(s) de Strong para la palabra.
     * Se omite si la traducción solo proporciona otras anotaciones para la palabra.
     */
    strongs?: string[];

    /**
     * La forma de la palabra que aparece en el diccionario (cita).
     * Se omite si la traducción no la proporciona.
     */
    lemma?: string;

    /**
     * El código de análisis morfológico para la palabra.
     * Se omite si la traducción no la proporciona.
     */
    morph?: string;

    /**
     * El puntero a la palabra en el texto fuente, en formato <sourceName> : <location> .
     * Se omite si la traducción no la proporciona.
     */
    srcloc?: string;

    /**
     * ¿Qué ocurrencia de la palabra fuente es esta palabra? 1-basado.
     * Se omite si la traducción no la proporciona.
     */
    occurrence?: number;

    /**
     * El número total de veces que aparece la palabra de origen.
     * Se omite si la traducción no la proporciona.
     */
    occurrences?: number;
}

/**
 * Define los datos completos de descarga de la traducción.
 * Se corresponde con el punto final /api/:translationId/complete.json.
 */
export interface TranslationComplete {
    /**
     * Los metadatos de la traducción.
     */
    translation: Translation;

    /**
     * La lista completa de libros con todos sus capítulos.
     */
    books: TranslationCompleteBook[];
}

/**
 * Descarga el libro en su traducción completa.
 */
export interface TranslationCompleteBook {
    /**
     * La identificación del libro.
     */
    id: string;

    /**
     * El nombre del libro según la traducción.
     */
    name: string;

    /**
     * El nombre común del libro.
     */
    commonName: string;

    /**
     * El título del libro.
     */
    title: string | null;

    /**
     * El orden del libro.
     */
    order: number;

    /**
     * El número de capítulos del libro.
     */
    numberOfChapters: number;

    /**
     * El número total de versículos del libro.
     */
    totalNumberOfVerses: number;

    /**
     * Si el libro es apócrifo.
     */
    isApocryphal?: boolean;

    /**
     * La lista completa de capítulos con todo su contenido.
     */
    chapters: TranslationCompleteChapter[];
}

/**
 * Un capítulo de la traducción completa para descargar.
 */
export interface TranslationCompleteChapter {
    /**
     * El número de versículos que contiene el capítulo.
     */
    numberOfVerses: number;

    /**
     * Los enlaces a las diferentes versiones de audio del capítulo.
     */
    thisChapterAudioLinks: TranslationBookChapterAudioLinks;

    /**
     * Los tiempos de audio (tiempos de inicio por verso, en segundos) para las diferentes versiones de audio del capítulo.
     *
     * A diferencia del valor `thisChapterAudioTimings` en el punto final de cada capítulo individual (que enlaza con "Obtener la sincronización de audio para un capítulo" más abajo), este contiene la sincronización en sí, ya que el objetivo de la descarga de la traducción completa es tener todo en un solo archivo.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsMap;

    /**
     * Enlace a las anotaciones a nivel de palabra del capítulo.
     * Se omite si el capítulo no tiene anotaciones a nivel de palabra.
     */
    thisChapterWordsLink?: string;

    /**
     * La información del capítulo.
     */
    chapter: ChapterData;
}

/**
 * Los tiempos de audio de un capítulo del libro, integrados directamente en lugar de enlazados.
 * Asigna un ID de lector a la lista de momentos (en segundos) en que comienza cada verso, en orden de verso.
 */
interface TranslationBookChapterAudioTimingsMap {
    [reader: string]: number[];
}