Standard Format

export interface TranslationBookChapter {
    /**
     * The translation information for the book chapter.
     */
    translation: Translation;

    /**
     * The book information for the book chapter.
     */
    book: TranslationBook;

    /**
     * The link to the current chapter.
     */
    thisChapterLink: string;

    /**
     * The links to different audio versions for the chapter.
     */
    thisChapterAudioLinks: TranslationBookChapterAudioLinks;

    /**
     * The links to the audio timings for different audio versions for the chapter.
     * Each link points at the audio timings file for that reader - see
     * "Get the Audio Timings for a Chapter" below.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsLinks;

    /**
     * The link to the next chapter.
     * Null if this is the last chapter in the translation.
     */
    nextChapterApiLink: string | null;

    /**
     * The links to different audio versions for the next chapter.
     * Null if this is the last chapter in the translation.
     */
    nextChapterAudioLinks: TranslationBookChapterAudioLinks | null;

    /**
     * The links to the audio timings for different audio versions for the next chapter.
     * Null if this is the last chapter in the translation.
     */
    nextChapterAudioTimings: TranslationBookChapterAudioTimingsLinks | null;

    /**
     * The link to the previous chapter.
     * Null if this is the first chapter in the translation.
     */
    previousChapterApiLink: string | null;

    /**
     * The links to different audio versions for the previous chapter.
     * Null if this is the first chapter in the translation.
     */
    previousChapterAudioLinks: TranslationBookChapterAudioLinks | null;

    /**
     * The links to the audio timings for different audio versions for the previous chapter.
     * Null if this is the first chapter in the translation.
     */
    previousChapterAudioTimings: TranslationBookChapterAudioTimingsLinks | null;

    /**
     * The link to the word-level annotations for the chapter.
     * Omitted if the chapter doesn't have any word-level annotations.
     */
    thisChapterWordsLink?: string;

    /**
     * The link to the word-level annotations for the next chapter.
     * Omitted if this is the last chapter in the translation, or if the next chapter
     * doesn't have any word-level annotations.
     */
    nextChapterWordsLink?: string;

    /**
     * The link to the word-level annotations for the previous chapter.
     * Omitted if this is the first chapter in the translation, or if the previous
     * chapter doesn't have any word-level annotations.
     */
    previousChapterWordsLink?: string;

    /**
     * The number of verses that the chapter contains.
     */
    numberOfVerses: number;

    /**
     * The link to the simplified version of this chapter.
     * Omitted if simplified chapters are not available.
     */
    simpleChapterApiLink?: string;

    /**
     * The information for the chapter.
     */
    chapter: ChapterData;
}

interface ChapterData {
    /**
     * The number of the chapter.
     */
    number: number;

    /**
     * The content of the chapter.
     */
    content: ChapterContent[];

    /**
     * The list of footnotes for the chapter.
     */
    footnotes: ChapterFootnote[];
}

/**
 * A union type that represents a single piece of chapter content.
 * A piece of chapter content can be one of the following things:
 * - A heading.
 * - A line break.
 * - A verse.
 * - A Hebrew Subtitle.
 */
type ChapterContent = ChapterHeading | ChapterLineBreak | ChapterVerse | ChapterHebrewSubtitle;

/**
 * A heading in a chapter.
 */
interface ChapterHeading {
    /**
     * Indicates that the content represents a heading.
     */
    type: 'heading';

    /**
     * The content for the heading.
     * If multiple strings are included in the array, they should be concatenated with a space.
     */
    content: string[];
}

/**
 * A line break in a chapter.
 */
interface ChapterLineBreak {
    /**
     * Indicates that the content represents a line break.
     */
    type: 'line_break';
}

/**
 * A Hebrew Subtitle in a chapter.
 * These are often used included as informational content that appeared in the original manuscripts.
 * For example, Psalms 49 has the Hebrew Subtitle "To the choirmaster. A Psalm of the Sons of Korah."
 */
interface ChapterHebrewSubtitle {
    /**
     * Indicates that the content represents a Hebrew Subtitle.
     */
    type: 'hebrew_subtitle';

    /**
     * The list of content that is contained in the subtitle.
     * Each element in the list could be a string, formatted text, or a footnote reference.
     */
    content: (string | FormattedText | VerseFootnoteReference)[];
}

/**
 * A verse in a chapter.
 */
interface ChapterVerse {
    /**
     * Indicates that the content is a verse.
     */
    type: 'verse';

    /**
     * The number of the verse.
     */
    number: number;

    /**
     * The list of content for the verse.
     * Each element in the list could be a string, formatted text, or a footnote reference.
     */
    content: (string | FormattedText | InlineHeading | InlineLineBreak | VerseFootnoteReference)[];
}

/**
 * Formatted text. That is, text that is formated in a particular manner.
 */
interface FormattedText {
    /**
     * The text that is formatted.
     */
    text: string;

    /**
     * Whether the text represents a poem.
     * The number indicates the level of indent.
     *
     * Common in Psalms.
     */
    poem?: number;

    /**
     * Whether the text represents the Words of Jesus.
     */
    wordsOfJesus?: boolean;
}

/**
 * Defines an interface that represents a heading that is embedded in a verse.
 */
interface InlineHeading {
    /**
     * The text of the heading.
     */
    heading: string;
}

/**
 * Defines an interface that represents a line break that is embedded in a verse.
 */
interface InlineLineBreak {
    lineBreak: true;
}


/**
 * A footnote reference in a verse or a Hebrew Subtitle.
 */
interface VerseFootnoteReference {
    /**
     * The ID of the note.
     */
    noteId: number;
}

/**
 * Information about a footnote.
 */
interface ChapterFootnote {
    /**
     * The ID of the note that is referenced.
     */
    noteId: number;

    /**
     * The text of the footnote.
     */
    text: string;

    /**
     * The verse reference for the footnote.
     */
    reference?: {
        chapter: number;
        verse: number;
    };

    /**
     * The caller that should be used for the footnote.
     * For footnotes, a "caller" is the character that is used in the text to reference to footnote.
     *
     * For example, in the text:
     * Hello (a) World
     *
     * ----
     * (a) This is a footnote.
     *
     * The "(a)" is the caller.
     *
     * If "+", then the caller should be autogenerated.
     * If null, then the caller should be empty.
     * If a string, then the caller should be that string.
     */
    caller: '+' | string | null;
}

/**
 * The audio links for a book chapter.
 */
interface TranslationBookChapterAudioLinks {
    /**
     * The reader for the chapter and the URL link to the audio file.
     */
    [reader: string]: string;
}

/**
 * The audio timings links for a book chapter.
 */
interface TranslationBookChapterAudioTimingsLinks {
    /**
     * The reader for the chapter and the API link to the audio timings file for that reader.
     */
    [reader: string]: string;
}

/**
 * Defines the audio timings for a book chapter, for a single reader.
 * Maps to the /api/{translation}/{book}/{chapter}.{reader}.audioTimings.json endpoint.
 */
export interface TranslationBookChapterAudioTimings {
    /**
     * The ID of the translation.
     */
    translationId: string;

    /**
     * The ID of the book.
     */
    bookId: string;

    /**
     * The number of the chapter.
     */
    chapterNumber: number;

    /**
     * The ID of the reader that these timings are for.
     */
    reader: string;

    /**
     * The link to the audio file that these timings are for.
     */
    audioLink: string;

    /**
     * The link to the information for this chapter.
     */
    thisChapterLink: string;

    /**
     * The link to the information for the next chapter.
     * Null if this is the last chapter in the translation.
     */
    nextChapterLink: string | null;

    /**
     * The link to the information for the previous chapter.
     * Null if this is the first chapter in the translation.
     */
    previousChapterLink: string | null;

    /**
     * The link to this audio timings file.
     */
    thisChapterAudioTimingsLink: string;

    /**
     * The link to the timings for the next chapter, for the same reader.
     * Null if this is the last chapter in the translation.
     */
    nextChapterAudioTimingsLink: string | null;

    /**
     * The link to the timings for the previous chapter, for the same reader.
     * Null if this is the first chapter in the translation.
     */
    previousChapterAudioTimingsLink: string | null;

    /**
     * The times in seconds at which each verse starts, in order.
     * The first number (index 0) is the time in the recording at which the first verse starts.
     */
    verses: number[];
}

export interface TranslationBookChapterWords {
    /**
     * The ID of the translation.
     */
    translationId: string;

    /**
     * The ID of the book.
     */
    bookId: string;

    /**
     * The number of the chapter.
     */
    chapterNumber: number;

    /**
     * The link to the information for this chapter.
     */
    thisChapterLink: string;

    /**
     * The link to the information for the next chapter.
     * Null if this is the last chapter in the translation.
     */
    nextChapterLink: string | null;

    /**
     * The link to the information for the previous chapter.
     * Null if this is the first chapter in the translation.
     */
    previousChapterLink: string | null;

    /**
     * The link to this words file.
     */
    thisChapterWordsLink: string;

    /**
     * The link to the words for the next chapter.
     * Null if this is the last chapter in the translation, or if the next chapter
     * doesn't have any word-level annotations.
     */
    nextChapterWordsLink: string | null;

    /**
     * The link to the words for the previous chapter.
     * Null if this is the first chapter in the translation, or if the previous chapter
     * doesn't have any word-level annotations.
     */
    previousChapterWordsLink: string | null;

    /**
     * The annotated words for each verse in the chapter, keyed by verse number.
     * Each list is in the order that the words occur in the verse.
     */
    verses: {
        [verseNumber: string]: ChapterWord[];
    };
}

interface ChapterWord {
    /**
     * The index of the item in the verse's content array that the annotation applies to.
     */
    contentIndex: number;

    /**
     * The index of the first character of the annotated word in the content item's text.
     */
    start: number;

    /**
     * The index after the last character of the annotated word in the content item's text.
     * That is, text.slice(start, end) is the annotated word.
     */
    end: number;

    /**
     * The Strong's number(s) for the word.
     * Omitted if the translation only provided other annotations for the word.
     */
    strongs?: string[];

    /**
     * The dictionary (citation) form of the word.
     * Omitted if the translation did not provide one.
     */
    lemma?: string;

    /**
     * The morphology parse code for the word.
     * Omitted if the translation did not provide one.
     */
    morph?: string;

    /**
     * The pointer to the word in the source text, in the <sourceName>:<location> format.
     * Omitted if the translation did not provide one.
     */
    srcloc?: string;

    /**
     * Which occurrence of the source word this word is. 1-based.
     * Omitted if the translation did not provide one.
     */
    occurrence?: number;

    /**
     * The total number of times that the source word occurs.
     * Omitted if the translation did not provide one.
     */
    occurrences?: number;
}

/**
 * Defines the complete translation download data.
 * Maps to the /api/:translationId/complete.json endpoint.
 */
export interface TranslationComplete {
    /**
     * The translation metadata.
     */
    translation: Translation;

    /**
     * The complete list of books with all their chapters.
     */
    books: TranslationCompleteBook[];
}

/**
 * A book in the complete translation download.
 */
export interface TranslationCompleteBook {
    /**
     * The ID of the book.
     */
    id: string;

    /**
     * The name of the book from the translation.
     */
    name: string;

    /**
     * The common name for the book.
     */
    commonName: string;

    /**
     * The title of the book.
     */
    title: string | null;

    /**
     * The order of the book.
     */
    order: number;

    /**
     * The number of chapters in the book.
     */
    numberOfChapters: number;

    /**
     * The total number of verses in the book.
     */
    totalNumberOfVerses: number;

    /**
     * Whether the book is apocryphal.
     */
    isApocryphal?: boolean;

    /**
     * The complete list of chapters with all content.
     */
    chapters: TranslationCompleteChapter[];
}

/**
 * A chapter in the complete translation download.
 */
export interface TranslationCompleteChapter {
    /**
     * The number of verses that the chapter contains.
     */
    numberOfVerses: number;

    /**
     * The links to different audio versions for the chapter.
     */
    thisChapterAudioLinks: TranslationBookChapterAudioLinks;

    /**
     * The audio timings (per-verse start times, in seconds) for different audio versions for
     * the chapter.
     *
     * Unlike `thisChapterAudioTimings` on the individual chapter endpoint (which links to
     * "Get the Audio Timings for a Chapter" below), this contains the timings themselves -
     * since the point of the complete translation download is to have everything in one file.
     */
    thisChapterAudioTimings: TranslationBookChapterAudioTimingsMap;

    /**
     * The link to the word-level annotations for the chapter.
     * Omitted if the chapter doesn't have any word-level annotations.
     */
    thisChapterWordsLink?: string;

    /**
     * The information for the chapter.
     */
    chapter: ChapterData;
}

/**
 * The audio timings for a book chapter, embedded directly rather than linked to.
 * Maps a reader ID to the list of times (in seconds) that each verse starts, in verse order.
 */
interface TranslationBookChapterAudioTimingsMap {
    [reader: string]: number[];
}