free-use-bible-api 0.2.0 → 0.4.0

package/dist/types/FreeUseBibleApi.d.ts

@@ -1,4 +1,4 @@
-import type { ApiAvailableDatasets, ApiAvailableTranslations, ApiCommentaryBook, ApiCommentaryBookChapter, ApiDatasetBook, ApiDatasetBookChapter, ApiDatasetBooks, ApiTranslationBook, ApiTranslationBookChapter, ApiTranslationBooks, ApiTranslationComplete, ChapterVerse } from './types.gen.js';
+import type { ApiAvailableDatasets, ApiAvailableTranslations, ApiCommentaryBook, ApiCommentaryBookChapter, ApiDatasetBook, ApiDatasetBookChapter, ApiDatasetBooks, ApiDatasetEntityBookChapter, ApiDatasetEvent, ApiDatasetEvents, ApiDatasetPeople, ApiDatasetPeopleGroup, ApiDatasetPeopleGroups, ApiDatasetPerson, ApiDatasetPlace, ApiDatasetPlaces, ApiSimpleCommentaryBookChapter, ApiSimpleTranslationBookChapter, ApiSimpleTranslationBookChapterWords, ApiSimpleTranslationComplete, ApiTranslationBook, ApiTranslationBookChapter, ApiTranslationBookChapterWords, ApiTranslationBooks, ApiTranslationComplete, ChapterVerse, ChapterWord, SimpleChapterVerse, SimpleChapterWord, SimpleTranslationCompleteChapter, TranslationCompleteChapter } from './types.gen.js';
 /**
  * Options for the FreeUseBibleApi class.
  */
@@ -37,6 +37,24 @@ export interface GetVerseTextOptions {
      */
     omitReference?: boolean;
 }
+/**
+ * A word-level annotation, paired with the text of the verse that it covers.
+ */
+export interface AnnotatedWord extends ChapterWord {
+    /**
+     * The text that the annotation applies to.
+     */
+    text: string;
+}
+/**
+ * A word-level annotation in a simplified chapter, paired with the text of the verse that it covers.
+ */
+export interface SimpleAnnotatedWord extends SimpleChapterWord {
+    /**
+     * The text that the annotation applies to.
+     */
+    text: string;
+}
 /**
  * A reference to a specific verse in a Bible translation, commentary, or dataset.
  */
@@ -83,6 +101,14 @@ export declare class FreeUseBibleApi {
      * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
      */
     getCompleteTranslation(translation: string, endpoint?: string): Promise<ApiTranslationComplete>;
+    /**
+     * Gets the complete content of a specific Bible translation, using the simplified chapter format.
+     *
+     * The results of this endpoint are very large, so the response is not cached.
+     * @param translation The ID of the translation to get the complete content for.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     */
+    getSimpleCompleteTranslation(translation: string, endpoint?: string): Promise<ApiSimpleTranslationComplete>;
     /**
      * Gets the list of available Bible commentaries from the API.
      * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
@@ -111,6 +137,63 @@ export declare class FreeUseBibleApi {
      * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
      */
     getDatasetBooks(dataset: string, endpoint?: string): Promise<ApiDatasetBooks>;
+    /**
+     * Gets the list of people for a given dataset.
+     * @param dataset The ID of the dataset to get the people for.
+     * @param endpoint The endpoint to use for the request. If not provided, then the default endpoint will be used.
+     */
+    getDatasetPeople(dataset: string, endpoint?: string): Promise<ApiDatasetPeople>;
+    /**
+     * Gets the information about a specific person for a given dataset.
+     * Includes the Bible references that mention the person and their relationships
+     * to other people, places, events, and people groups.
+     * @param dataset The ID of the dataset to get the person for.
+     * @param person The ID of the person to get.
+     * @param endpoint The endpoint to use for the request. If not provided, then the default endpoint will be used.
+     */
+    getDatasetPerson(dataset: string, person: string, endpoint?: string): Promise<ApiDatasetPerson>;
+    /**
+     * Gets the list of places for a given dataset.
+     * @param dataset The ID of the dataset to get the places for.
+     * @param endpoint The endpoint to use for the request. If not provided, then the default endpoint will be used.
+     */
+    getDatasetPlaces(dataset: string, endpoint?: string): Promise<ApiDatasetPlaces>;
+    /**
+     * Gets the information about a specific place for a given dataset.
+     * Includes the Bible references that mention the place and its related people and events.
+     * @param dataset The ID of the dataset to get the place for.
+     * @param place The ID of the place to get.
+     * @param endpoint The endpoint to use for the request. If not provided, then the default endpoint will be used.
+     */
+    getDatasetPlace(dataset: string, place: string, endpoint?: string): Promise<ApiDatasetPlace>;
+    /**
+     * Gets the list of events for a given dataset.
+     * @param dataset The ID of the dataset to get the events for.
+     * @param endpoint The endpoint to use for the request. If not provided, then the default endpoint will be used.
+     */
+    getDatasetEvents(dataset: string, endpoint?: string): Promise<ApiDatasetEvents>;
+    /**
+     * Gets the information about a specific event for a given dataset.
+     * Includes the Bible references that describe the event and its related people, places, and people groups.
+     * @param dataset The ID of the dataset to get the event for.
+     * @param event The ID of the event to get.
+     * @param endpoint The endpoint to use for the request. If not provided, then the default endpoint will be used.
+     */
+    getDatasetEvent(dataset: string, event: string, endpoint?: string): Promise<ApiDatasetEvent>;
+    /**
+     * Gets the list of people groups for a given dataset.
+     * @param dataset The ID of the dataset to get the people groups for.
+     * @param endpoint The endpoint to use for the request. If not provided, then the default endpoint will be used.
+     */
+    getDatasetPeopleGroups(dataset: string, endpoint?: string): Promise<ApiDatasetPeopleGroups>;
+    /**
+     * Gets the information about a specific people group for a given dataset.
+     * Includes the members of the group and the events that the group participated in.
+     * @param dataset The ID of the dataset to get the people group for.
+     * @param group The ID of the people group to get.
+     * @param endpoint The endpoint to use for the request. If not provided, then the default endpoint will be used.
+     */
+    getDatasetPeopleGroup(dataset: string, group: string, endpoint?: string): Promise<ApiDatasetPeopleGroup>;
     /**
      * Gets the content of a specific chapter of a specific book for a specific Bible translation.
      * @param translation The ID of the translation to get the chapter for.
@@ -119,6 +202,80 @@ export declare class FreeUseBibleApi {
      * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
      */
     getTranslationBookChapter(translation: string, book: string, chapter: number | string, endpoint?: string): Promise<ApiTranslationBookChapter>;
+    /**
+     * Gets the word-level annotations (Strong's numbers and related source data) for a specific chapter of a specific book for a specific Bible translation.
+     *
+     * Only some translations have word-level annotations. This request will fail for chapters that don't have any.
+     * Use `getChapterWords()` to get the annotations for a chapter that you have already loaded, which returns null instead of failing.
+     * @param translation The ID of the translation to get the annotations for.
+     * @param book The ID of the book to get the annotations for.
+     * @param chapter The chapter number to get the annotations for.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     */
+    getTranslationBookChapterWords(translation: string, book: string, chapter: number | string, endpoint?: string): Promise<ApiTranslationBookChapterWords>;
+    /**
+     * Gets the word-level annotations for the given chapter, if it has any.
+     * @param chapter The chapter to get the annotations for.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     * @returns The annotations for the chapter, or null if the chapter doesn't have any.
+     */
+    getChapterWords(chapter: ApiTranslationBookChapter, endpoint?: string): Promise<ApiTranslationBookChapterWords | null>;
+    /**
+     * Gets the word-level annotations for the given chapter of a complete translation download, if it has any.
+     * @param chapter The chapter to get the annotations for.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     * @returns The annotations for the chapter, or null if the chapter doesn't have any.
+     */
+    getChapterWords(chapter: TranslationCompleteChapter, endpoint?: string): Promise<ApiTranslationBookChapterWords | null>;
+    /**
+     * Gets the content of a specific chapter of a specific book for a specific Bible translation, using the simplified chapter format.
+     *
+     * In the simplified format, each verse's content is a single string instead of a list of formatted content, and footnotes, inline headings, the Words of Jesus, and poetry are represented as offset ranges into that string.
+     * @param translation The ID of the translation to get the chapter for.
+     * @param book The ID of the book to get the chapter for.
+     * @param chapter The chapter number to get.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     */
+    getSimpleTranslationBookChapter(translation: string, book: string, chapter: number | string, endpoint?: string): Promise<ApiSimpleTranslationBookChapter>;
+    /**
+     * Gets the word-level annotations (Strong's numbers and related source data) for a specific chapter of a specific book for a specific Bible translation, with their offsets remapped onto the text of each simplified verse.
+     *
+     * Use this instead of `getTranslationBookChapterWords()` when working with the simplified chapter format, since the offsets in the regular annotations are anchored to a verse's content array instead of its plain text.
+     * Use `getSimpleChapterWords()` to get the annotations for a simplified chapter that you have already loaded, which returns null instead of failing.
+     * @param translation The ID of the translation to get the annotations for.
+     * @param book The ID of the book to get the annotations for.
+     * @param chapter The chapter number to get the annotations for.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     */
+    getSimpleTranslationBookChapterWords(translation: string, book: string, chapter: number | string, endpoint?: string): Promise<ApiSimpleTranslationBookChapterWords>;
+    /**
+     * Gets the simplified version of a given chapter, if available.
+     * @param chapter The chapter to get the simplified version of.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     * @returns The simplified chapter, or null if simplified chapters aren't available for it.
+     */
+    getSimpleChapter(chapter: ApiCommentaryBookChapter, endpoint?: string): Promise<ApiSimpleCommentaryBookChapter | null>;
+    /**
+     * Gets the simplified version of a given chapter, if available.
+     * @param chapter The chapter to get the simplified version of.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     * @returns The simplified chapter, or null if simplified chapters aren't available for it.
+     */
+    getSimpleChapter(chapter: ApiTranslationBookChapter, endpoint?: string): Promise<ApiSimpleTranslationBookChapter | null>;
+    /**
+     * Gets the word-level annotations for the given simplified chapter, if it has any.
+     * @param chapter The simplified chapter to get the annotations for.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     * @returns The annotations for the chapter, or null if the chapter doesn't have any.
+     */
+    getSimpleChapterWords(chapter: ApiSimpleTranslationBookChapter, endpoint?: string): Promise<ApiSimpleTranslationBookChapterWords | null>;
+    /**
+     * Gets the word-level annotations for the given chapter of a simplified complete translation download, if it has any.
+     * @param chapter The chapter to get the annotations for.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     * @returns The annotations for the chapter, or null if the chapter doesn't have any.
+     */
+    getSimpleChapterWords(chapter: SimpleTranslationCompleteChapter, endpoint?: string): Promise<ApiSimpleTranslationBookChapterWords | null>;
     /**
      * Gets the content of a specific chapter of a specific book for a specific Bible commentary.
      * @param commentary The ID of the commentary to get the chapter for.
@@ -127,14 +284,26 @@ export declare class FreeUseBibleApi {
      * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
      */
     getCommentaryBookChapter(commentary: string, book: string, chapter: number | string, endpoint?: string): Promise<ApiTranslationBookChapter>;
+    /**
+     * Gets the content of a specific chapter of a specific book for a specific Bible commentary, using the simplified chapter format.
+     * @param commentary The ID of the commentary to get the chapter for.
+     * @param book The ID of the book to get the chapter for.
+     * @param chapter The chapter number to get.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     */
+    getSimpleCommentaryBookChapter(commentary: string, book: string, chapter: number | string, endpoint?: string): Promise<ApiSimpleCommentaryBookChapter>;
     /**
      * Gets the content of a specific chapter of a specific book for a specific dataset.
+     *
+     * For cross reference datasets, this is the list of cross references for each verse
+     * in the chapter. For entity datasets (such as "theographic"), this is the people,
+     * places, and events that appear in the chapter.
      * @param dataset The ID of the dataset to get the chapter for.
      * @param book The ID of the book to get the chapter for.
      * @param chapter The chapter number to get.
      * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
      */
-    getDatasetBookChapter(dataset: string, book: string, chapter: number | string, endpoint?: string): Promise<ApiDatasetBookChapter>;
+    getDatasetBookChapter(dataset: string, book: string, chapter: number | string, endpoint?: string): Promise<ApiDatasetBookChapter | ApiDatasetEntityBookChapter>;
     /**
      * Gets the next chapter for a given chapter, if available.
      * @param chapter The chapter to get the next chapter for.
@@ -156,6 +325,20 @@ export declare class FreeUseBibleApi {
      * @returns The next chapter, or null if there is no next chapter.
      */
     getNextChapter(chapter: ApiDatasetBookChapter, endpoint?: string): Promise<ApiDatasetBookChapter | null>;
+    /**
+     * Gets the next chapter for a given chapter, if available.
+     * @param chapter The chapter to get the next chapter for.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     * @returns The next chapter, or null if there is no next chapter.
+     */
+    getNextChapter(chapter: ApiSimpleCommentaryBookChapter, endpoint?: string): Promise<ApiSimpleCommentaryBookChapter | null>;
+    /**
+     * Gets the next chapter for a given chapter, if available.
+     * @param chapter The chapter to get the next chapter for.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     * @returns The next chapter, or null if there is no next chapter.
+     */
+    getNextChapter(chapter: ApiSimpleTranslationBookChapter, endpoint?: string): Promise<ApiSimpleTranslationBookChapter | null>;
     /**
      * Gets the previous chapter for a given chapter, if available.
      * @param chapter The chapter to get the previous chapter for.
@@ -177,6 +360,20 @@ export declare class FreeUseBibleApi {
      * @returns The previous chapter, or null if there is no previous chapter.
      */
     getPreviousChapter(chapter: ApiDatasetBookChapter, endpoint?: string): Promise<ApiDatasetBookChapter | null>;
+    /**
+     * Gets the previous chapter for a given chapter, if available.
+     * @param chapter The chapter to get the previous chapter for.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     * @returns The previous chapter, or null if there is no previous chapter.
+     */
+    getPreviousChapter(chapter: ApiSimpleCommentaryBookChapter, endpoint?: string): Promise<ApiSimpleCommentaryBookChapter | null>;
+    /**
+     * Gets the previous chapter for a given chapter, if available.
+     * @param chapter The chapter to get the previous chapter for.
+     * @param endpoint The API endpoint to use for the request. If not provided, the default endpoint will be used.
+     * @returns The previous chapter, or null if there is no previous chapter.
+     */
+    getPreviousChapter(chapter: ApiSimpleTranslationBookChapter, endpoint?: string): Promise<ApiSimpleTranslationBookChapter | null>;
     /**
      * Gets the first chapter for a given book, if available.
      * @param book The book to get the first chapter for.
@@ -241,6 +438,45 @@ export declare class FreeUseBibleApi {
      * @param options Options for getting the chapter text.
      */
     getChapterVerseText(chapter: ApiTranslationBookChapter, options?: GetChapterTextOptions): string;
+    /**
+     * Gets the verse text for the given simplified chapter.
+     * By default, the returned text includes markers for verse numbers and a reference to the chapter, but these can be omitted by passing options to the `options` parameter.
+     * @param chapter The simplified chapter to get the text for.
+     * @param options Options for getting the chapter text.
+     */
+    getSimpleChapterVerseText(chapter: ApiSimpleTranslationBookChapter, options?: GetChapterTextOptions): string;
+    /**
+     * Gets the text that the given word-level annotation applies to.
+     *
+     * Annotations are anchored to a range of characters in a single item of the verse's content,
+     * so that the ranges stay correct for verses whose content is split into multiple items,
+     * such as poem lines and the words of Jesus.
+     * @param verse The verse that the annotation is in.
+     * @param word The annotation to get the text for.
+     * @returns The annotated text, or an empty string if the annotation doesn't point at any text.
+     */
+    getWordText(verse: ChapterVerse, word: ChapterWord): string;
+    /**
+     * Gets the word-level annotations for the given verse, paired with the text that each one applies to.
+     * @param verse The verse to get the annotations for.
+     * @param words The annotations for the chapter that the verse is in.
+     * @returns The annotations for the verse, in the order that they occur. Empty if the verse has no annotations.
+     */
+    getVerseWords(verse: ChapterVerse, words: ApiTranslationBookChapterWords): AnnotatedWord[];
+    /**
+     * Gets the text that the given simplified word-level annotation applies to.
+     * @param verse The simplified verse that the annotation is in.
+     * @param word The annotation to get the text for.
+     * @returns The annotated text.
+     */
+    getSimpleWordText(verse: SimpleChapterVerse, word: SimpleChapterWord): string;
+    /**
+     * Gets the word-level annotations for the given simplified verse, paired with the text that each one applies to.
+     * @param verse The simplified verse to get the annotations for.
+     * @param words The simplified annotations for the chapter that the verse is in.
+     * @returns The annotations for the verse, in the order that they occur. Empty if the verse has no annotations.
+     */
+    getSimpleVerseWords(verse: SimpleChapterVerse, words: ApiSimpleTranslationBookChapterWords): SimpleAnnotatedWord[];
     private _getJson;
     private _buildUrl;
 }