free-use-bible-api 0.2.0 → 0.4.0

package/README.md

@@ -58,28 +58,74 @@ const api = new FreeUseBibleApi({
 -   `getAvailableTranslations(endpoint?)`
 -   `getTranslationBooks(translation, endpoint?)`
 -   `getTranslationBookChapter(translation, book, chapter, endpoint?)`
+-   `getTranslationBookChapterWords(translation, book, chapter, endpoint?)`
 -   `getCompleteTranslation(translation, endpoint?)`
+-   `getSimpleTranslationBookChapter(translation, book, chapter, endpoint?)`
+-   `getSimpleTranslationBookChapterWords(translation, book, chapter, endpoint?)`
+-   `getSimpleCompleteTranslation(translation, endpoint?)`
 
-`getCompleteTranslation()` disables per-request cache internally because payloads are typically large.
+`getCompleteTranslation()` and `getSimpleCompleteTranslation()` disable per-request cache internally because payloads are typically large.
 
 ### Commentaries
 
 -   `getAvailableCommentaries(endpoint?)`
 -   `getCommentaryBooks(commentary, endpoint?)`
 -   `getCommentaryBookChapter(commentary, book, chapter, endpoint?)`
+-   `getSimpleCommentaryBookChapter(commentary, book, chapter, endpoint?)`
 
 ### Datasets
 
 -   `getAvailableDatasets(endpoint?)`
 -   `getDatasetBooks(dataset, endpoint?)`
--   `getDatasetBookChapter(dataset, book, chapter, endpoint?)`
+-   `getDatasetBookChapter(dataset, book, chapter, endpoint?)` - returns cross references for cross reference datasets, or the people, places, and events that appear in the chapter for entity datasets (such as `theographic`)
+-   `getDatasetPeople(dataset, endpoint?)`
+-   `getDatasetPerson(dataset, person, endpoint?)`
+-   `getDatasetPlaces(dataset, endpoint?)`
+-   `getDatasetPlace(dataset, place, endpoint?)`
+-   `getDatasetEvents(dataset, endpoint?)`
+-   `getDatasetEvent(dataset, event, endpoint?)`
+-   `getDatasetPeopleGroups(dataset, endpoint?)`
+-   `getDatasetPeopleGroup(dataset, group, endpoint?)`
 
 ### Chapter Navigation Helpers
 
 -   `getNextChapter(chapter, endpoint?)`
 -   `getPreviousChapter(chapter, endpoint?)`
 
-These helpers work with translation, commentary, and dataset chapter responses.
+### Chapter & Verse Helpers
+
+-   `getVerseText(verse)`
+-   `getChapterVerseText(chapter)`
+
+These helpers work with translation, commentary, and dataset chapter responses, as well as simplified translation and commentary chapter responses.
+
+### Word Annotations
+
+Some translations include word-level annotations (Strong's numbers and related source data) for their chapters.
+
+-   `getChapterWords(chapter, endpoint?)` - gets the annotations for a chapter you already loaded, or `null` if it doesn't have any.
+-   `getWordText(verse, word)` - gets the text that a single annotation applies to.
+-   `getVerseWords(verse, words)` - gets the annotations for a verse, each paired with the text it applies to.
+
+Each annotation is anchored to a range of characters in a single item of a verse's `content` array: `contentIndex` is the index of the item, and `start`/`end` are character offsets into that item's text (`end` is exclusive). Anchoring per content item keeps the offsets correct for verses whose content is split into multiple items, such as poem lines and the words of Jesus.
+
+`getWordText()` and `getVerseWords()` resolve those offsets for you, so you don't have to walk the content array yourself.
+
+### Simplified Chapters
+
+Every translation and commentary chapter can also be fetched in a simplified format, where each verse's content is a single string instead of a list of formatted content. Footnotes, inline headings, the Words of Jesus, and poetry are represented as offset ranges into that string instead of being split across multiple content items.
+
+-   `getSimpleTranslationBookChapter(translation, book, chapter, endpoint?)`
+-   `getSimpleCommentaryBookChapter(commentary, book, chapter, endpoint?)`
+-   `getSimpleCompleteTranslation(translation, endpoint?)`
+-   `getSimpleChapter(chapter, endpoint?)` - follows a chapter's `simpleChapterApiLink`, or `null` if simplified chapters aren't available for it.
+-   `getSimpleTranslationBookChapterWords(translation, book, chapter, endpoint?)` / `getSimpleChapterWords(chapter, endpoint?)` - the same as the regular word annotations, but with offsets into the simplified verse text instead of a verse's content array.
+-   `getSimpleWordText(verse, word)` / `getSimpleVerseWords(verse, words)` - the same as `getWordText()`/`getVerseWords()`, but for simplified verses and annotations.
+-   `getSimpleChapterVerseText(chapter, options?)` - the same as `getChapterVerseText()`, but for a simplified chapter.
+
+`getNextChapter()` and `getPreviousChapter()` also accept simplified chapters, returning the next/previous simplified chapter.
+
+Datasets don't have a simplified format.
 
 ## Examples
 
@@ -121,6 +167,46 @@ console.log(next?.chapter.number);
 console.log(previous?.chapter.number);
 ```
 
+### Read the Strong's numbers for a chapter
+
+```ts
+const chapter = await api.getTranslationBookChapter('engwebp', 'JHN', 1);
+const words = await api.getChapterWords(chapter);
+
+if (!words) {
+    // This translation has no word-level annotations for the chapter.
+    return;
+}
+
+for (const content of chapter.chapter.content) {
+    if (content.type !== 'verse') {
+        continue;
+    }
+
+    for (const word of api.getVerseWords(content, words)) {
+        console.log(word.text, word.strongs);
+    }
+}
+
+// In [ 'G1722' ]
+// the [ 'G1722' ]
+// beginning [ 'G0746' ]
+// ...
+```
+
+### Read a simplified chapter
+
+```ts
+const chapter = await api.getSimpleTranslationBookChapter('BSB', 'JHN', 1);
+
+for (const content of chapter.chapter.content) {
+    if (content.type !== 'verse') {
+        continue;
+    }
+    console.log(content.number, content.text);
+}
+```
+
 ## Direct HTTP Endpoints
 
 ### Translation endpoints
@@ -128,19 +214,32 @@ console.log(previous?.chapter.number);
 -   `GET /api/available_translations.json`
 -   `GET /api/{translation}/books.json`
 -   `GET /api/{translation}/{book}/{chapter}.json`
+-   `GET /api/{translation}/{book}/{chapter}.words.json`
 -   `GET /api/{translation}/complete.json`
+-   `GET /api/{translation}/{book}/{chapter}.simple.json`
+-   `GET /api/{translation}/{book}/{chapter}.words.simple.json`
+-   `GET /api/{translation}/complete.simple.json`
 
 ### Commentary endpoints
 
 -   `GET /api/available_commentaries.json`
--   `GET /api/{commentary}/books.json`
--   `GET /api/{commentary}/{book}/{chapter}.json`
+-   `GET /api/c/{commentary}/books.json`
+-   `GET /api/c/{commentary}/{book}/{chapter}.json`
+-   `GET /api/c/{commentary}/{book}/{chapter}.simple.json`
 
 ### Dataset endpoints
 
 -   `GET /api/available_datasets.json`
 -   `GET /api/d/{dataset}/books.json`
 -   `GET /api/d/{dataset}/{book}/{chapter}.json`
+-   `GET /api/d/{dataset}/people.json`
+-   `GET /api/d/{dataset}/people/{person}.json`
+-   `GET /api/d/{dataset}/places.json`
+-   `GET /api/d/{dataset}/places/{place}.json`
+-   `GET /api/d/{dataset}/events.json`
+-   `GET /api/d/{dataset}/events/{event}.json`
+-   `GET /api/d/{dataset}/groups.json`
+-   `GET /api/d/{dataset}/groups/{group}.json`
 
 Example requests:
 

package/dist/cjs/FreeUseBibleApi.cjs

@@ -54,6 +54,21 @@ class FreeUseBibleApi {
       false
     );
   }
+  /**
+   * 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.
+   */
+  async getSimpleCompleteTranslation(translation, endpoint) {
+    const encodedTranslation = encodeURIComponent(translation);
+    return this._getJson(
+      `api/${encodedTranslation}/complete.simple.json`,
+      endpoint,
+      false
+    );
+  }
   /**
    * 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.
@@ -94,7 +109,7 @@ class FreeUseBibleApi {
   async getCommentaryBooks(commentary, endpoint) {
     const encodedCommentary = encodeURIComponent(commentary);
     return this._getJson(
-      `api/${encodedCommentary}/books.json`,
+      `api/c/${encodedCommentary}/books.json`,
       endpoint
     );
   }
@@ -110,6 +125,115 @@ class FreeUseBibleApi {
       endpoint
     );
   }
+  /**
+   * 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.
+   */
+  async getDatasetPeople(dataset, endpoint) {
+    const encodedDataset = encodeURIComponent(dataset);
+    return this._getJson(
+      `api/d/${encodedDataset}/people.json`,
+      endpoint
+    );
+  }
+  /**
+   * 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.
+   */
+  async getDatasetPerson(dataset, person, endpoint) {
+    const encodedDataset = encodeURIComponent(dataset);
+    const encodedPerson = encodeURIComponent(person);
+    return this._getJson(
+      `api/d/${encodedDataset}/people/${encodedPerson}.json`,
+      endpoint
+    );
+  }
+  /**
+   * 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.
+   */
+  async getDatasetPlaces(dataset, endpoint) {
+    const encodedDataset = encodeURIComponent(dataset);
+    return this._getJson(
+      `api/d/${encodedDataset}/places.json`,
+      endpoint
+    );
+  }
+  /**
+   * 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.
+   */
+  async getDatasetPlace(dataset, place, endpoint) {
+    const encodedDataset = encodeURIComponent(dataset);
+    const encodedPlace = encodeURIComponent(place);
+    return this._getJson(
+      `api/d/${encodedDataset}/places/${encodedPlace}.json`,
+      endpoint
+    );
+  }
+  /**
+   * 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.
+   */
+  async getDatasetEvents(dataset, endpoint) {
+    const encodedDataset = encodeURIComponent(dataset);
+    return this._getJson(
+      `api/d/${encodedDataset}/events.json`,
+      endpoint
+    );
+  }
+  /**
+   * 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.
+   */
+  async getDatasetEvent(dataset, event, endpoint) {
+    const encodedDataset = encodeURIComponent(dataset);
+    const encodedEvent = encodeURIComponent(event);
+    return this._getJson(
+      `api/d/${encodedDataset}/events/${encodedEvent}.json`,
+      endpoint
+    );
+  }
+  /**
+   * 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.
+   */
+  async getDatasetPeopleGroups(dataset, endpoint) {
+    const encodedDataset = encodeURIComponent(dataset);
+    return this._getJson(
+      `api/d/${encodedDataset}/groups.json`,
+      endpoint
+    );
+  }
+  /**
+   * 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.
+   */
+  async getDatasetPeopleGroup(dataset, group, endpoint) {
+    const encodedDataset = encodeURIComponent(dataset);
+    const encodedGroup = encodeURIComponent(group);
+    return this._getJson(
+      `api/d/${encodedDataset}/groups/${encodedGroup}.json`,
+      endpoint
+    );
+  }
   /**
    * 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.
@@ -126,6 +250,86 @@ class FreeUseBibleApi {
       endpoint
     );
   }
+  /**
+   * 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.
+   */
+  async getTranslationBookChapterWords(translation, book, chapter, endpoint) {
+    const encodedTranslation = encodeURIComponent(translation);
+    const encodedBook = encodeURIComponent(book);
+    const encodedChapter = encodeURIComponent(String(chapter));
+    return this._getJson(
+      `api/${encodedTranslation}/${encodedBook}/${encodedChapter}.words.json`,
+      endpoint
+    );
+  }
+  async getChapterWords(chapter, endpoint) {
+    if (!chapter.thisChapterWordsLink) {
+      return null;
+    }
+    return this._getJson(
+      chapter.thisChapterWordsLink,
+      endpoint
+    );
+  }
+  /**
+   * 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.
+   */
+  async getSimpleTranslationBookChapter(translation, book, chapter, endpoint) {
+    const encodedTranslation = encodeURIComponent(translation);
+    const encodedBook = encodeURIComponent(book);
+    const encodedChapter = encodeURIComponent(String(chapter));
+    return this._getJson(
+      `api/${encodedTranslation}/${encodedBook}/${encodedChapter}.simple.json`,
+      endpoint
+    );
+  }
+  /**
+   * 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.
+   */
+  async getSimpleTranslationBookChapterWords(translation, book, chapter, endpoint) {
+    const encodedTranslation = encodeURIComponent(translation);
+    const encodedBook = encodeURIComponent(book);
+    const encodedChapter = encodeURIComponent(String(chapter));
+    return this._getJson(
+      `api/${encodedTranslation}/${encodedBook}/${encodedChapter}.words.simple.json`,
+      endpoint
+    );
+  }
+  async getSimpleChapter(chapter, endpoint) {
+    if (!chapter.simpleChapterApiLink) {
+      return null;
+    }
+    return this._getJson(chapter.simpleChapterApiLink, endpoint);
+  }
+  async getSimpleChapterWords(chapter, endpoint) {
+    if (!chapter.thisChapterWordsLink) {
+      return null;
+    }
+    return this._getJson(
+      chapter.thisChapterWordsLink,
+      endpoint
+    );
+  }
   /**
    * 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.
@@ -138,12 +342,32 @@ class FreeUseBibleApi {
     const encodedBook = encodeURIComponent(book);
     const encodedChapter = encodeURIComponent(String(chapter));
     return this._getJson(
-      `api/${encodedCommentary}/${encodedBook}/${encodedChapter}.json`,
+      `api/c/${encodedCommentary}/${encodedBook}/${encodedChapter}.json`,
+      endpoint
+    );
+  }
+  /**
+   * 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.
+   */
+  async getSimpleCommentaryBookChapter(commentary, book, chapter, endpoint) {
+    const encodedCommentary = encodeURIComponent(commentary);
+    const encodedBook = encodeURIComponent(book);
+    const encodedChapter = encodeURIComponent(String(chapter));
+    return this._getJson(
+      `api/c/${encodedCommentary}/${encodedBook}/${encodedChapter}.simple.json`,
       endpoint
     );
   }
   /**
    * 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.
@@ -259,6 +483,86 @@ ${content.trim()}`;
     }
     return content.trim();
   }
+  /**
+   * 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, options = {}) {
+    let content = "";
+    for (let chapterContent of chapter.chapter.content) {
+      if (chapterContent.type === "verse") {
+        if (!options.omitVerseNumbers) {
+          content += `[${chapterContent.number}] `;
+        }
+        content += chapterContent.text.trim() + " ";
+      } else if (chapterContent.type === "line_break") {
+        content = content.trim() + "\n";
+      }
+    }
+    if (!options.omitReference) {
+      content = `${this.formatReference(chapter.book, {
+        chapter: chapter.chapter.number
+      })}
+${content.trim()}`;
+    }
+    return content.trim();
+  }
+  /**
+   * 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, word) {
+    const content = verse.content[word.contentIndex];
+    if (typeof content === "string") {
+      return content.slice(word.start, word.end);
+    } else if (typeof content === "object" && content !== null && "text" in content) {
+      return content.text.slice(word.start, word.end);
+    }
+    return "";
+  }
+  /**
+   * 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, words) {
+    const verseWords = words.verses[verse.number.toString()] ?? [];
+    return verseWords.map((word) => ({
+      ...word,
+      text: this.getWordText(verse, word)
+    }));
+  }
+  /**
+   * 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, word) {
+    return verse.text.slice(word.start, word.end);
+  }
+  /**
+   * 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, words) {
+    const verseWords = words.verses[verse.number.toString()] ?? [];
+    return verseWords.map((word) => ({
+      ...word,
+      text: this.getSimpleWordText(verse, word)
+    }));
+  }
   _getJson(path, endpoint, useCache = true) {
     const url = this._buildUrl(path, endpoint);
     const existing = this._responseCache.get(url);