free-use-bible-api 0.2.0 → 0.3.0

package/README.md

@@ -1,170 +1,253 @@
-# Free Use Bible API
-
-TypeScript and JavaScript client for the public Free Use Bible API:
-
--   `https://bible.helloao.org`
-
-## Installation
-
-```bash
-npm install free-use-bible-api
-```
-
-```bash
-pnpm add free-use-bible-api
-```
-
-```bash
-yarn add free-use-bible-api
-```
-
-## Quick Start
-
-```ts
-import { FreeUseBibleApi } from 'free-use-bible-api';
-
-const api = new FreeUseBibleApi();
-
-const available = await api.getAvailableTranslations();
-console.log('Total translations:', available.translations.length);
-
-const books = await api.getTranslationBooks('BSB');
-console.log('Books in BSB:', books.books.length);
-
-const chapter = await api.getTranslationBookChapter('BSB', 'GEN', 1);
-console.log('Verses in Genesis 1:', chapter.numberOfVerses);
-```
-
-## Client Options
-
-You can customize the client with `FreeUseBibleApiOptions`:
-
-```ts
-import { FreeUseBibleApi } from 'free-use-bible-api';
-
-const api = new FreeUseBibleApi({
-    endpoint: 'https://bible.helloao.org/',
-    useCache: true,
-});
-```
-
--   `endpoint`: Base API endpoint.
--   `useCache`: Enables in-memory response caching (default: `true`).
-
-## API Methods
-
-### Translations
-
--   `getAvailableTranslations(endpoint?)`
--   `getTranslationBooks(translation, endpoint?)`
--   `getTranslationBookChapter(translation, book, chapter, endpoint?)`
--   `getCompleteTranslation(translation, endpoint?)`
-
-`getCompleteTranslation()` disables per-request cache internally because payloads are typically large.
-
-### Commentaries
-
--   `getAvailableCommentaries(endpoint?)`
--   `getCommentaryBooks(commentary, endpoint?)`
--   `getCommentaryBookChapter(commentary, book, chapter, endpoint?)`
-
-### Datasets
-
--   `getAvailableDatasets(endpoint?)`
--   `getDatasetBooks(dataset, endpoint?)`
--   `getDatasetBookChapter(dataset, book, chapter, endpoint?)`
-
-### Chapter Navigation Helpers
-
--   `getNextChapter(chapter, endpoint?)`
--   `getPreviousChapter(chapter, endpoint?)`
-
-These helpers work with translation, commentary, and dataset chapter responses.
-
-## Examples
-
-### Get a complete translation
-
-```ts
-const complete = await api.getCompleteTranslation('BSB');
-console.log(complete.translation.id);
-console.log(complete.books.length);
-```
-
-### Read a commentary chapter
-
-```ts
-const comm = await api.getCommentaryBookChapter('matthew_henry', 'GEN', 1);
-console.log(comm.book.name);
-```
-
-### Read a dataset chapter
-
-```ts
-const dataChapter = await api.getDatasetBookChapter(
-    'cross_references',
-    'JHN',
-    3
-);
-console.log(dataChapter.book.name);
-```
-
-### Navigate to next/previous chapter
-
-```ts
-const current = await api.getTranslationBookChapter('BSB', 'GEN', 1);
-
-const next = await api.getNextChapter(current);
-const previous = await api.getPreviousChapter(current);
-
-console.log(next?.chapter.number);
-console.log(previous?.chapter.number);
-```
-
-## Direct HTTP Endpoints
-
-### Translation endpoints
-
--   `GET /api/available_translations.json`
--   `GET /api/{translation}/books.json`
--   `GET /api/{translation}/{book}/{chapter}.json`
--   `GET /api/{translation}/complete.json`
-
-### Commentary endpoints
-
--   `GET /api/available_commentaries.json`
--   `GET /api/{commentary}/books.json`
--   `GET /api/{commentary}/{book}/{chapter}.json`
-
-### Dataset endpoints
-
--   `GET /api/available_datasets.json`
--   `GET /api/d/{dataset}/books.json`
--   `GET /api/d/{dataset}/{book}/{chapter}.json`
-
-Example requests:
-
-```bash
-curl https://bible.helloao.org/api/available_translations.json
-curl https://bible.helloao.org/api/BSB/books.json
-curl https://bible.helloao.org/api/BSB/GEN/1.json
-curl https://bible.helloao.org/api/available_commentaries.json
-curl https://bible.helloao.org/api/available_datasets.json
-```
-
-## Error Handling
-
-Methods throw on non-2xx responses.
-
-A 404 response usually means one of the path values is invalid, for example:
-
--   translation
--   commentary
--   dataset
--   book
--   chapter
-
-## Notes
-
--   Uses the global `fetch` API.
--   For Node.js, use a runtime that provides `fetch` (Node 18+ recommended) or polyfill it.
+# Free Use Bible API
+
+TypeScript and JavaScript client for the public Free Use Bible API:
+
+-   `https://bible.helloao.org`
+
+## Installation
+
+```bash
+npm install free-use-bible-api
+```
+
+```bash
+pnpm add free-use-bible-api
+```
+
+```bash
+yarn add free-use-bible-api
+```
+
+## Quick Start
+
+```ts
+import { FreeUseBibleApi } from 'free-use-bible-api';
+
+const api = new FreeUseBibleApi();
+
+const available = await api.getAvailableTranslations();
+console.log('Total translations:', available.translations.length);
+
+const books = await api.getTranslationBooks('BSB');
+console.log('Books in BSB:', books.books.length);
+
+const chapter = await api.getTranslationBookChapter('BSB', 'GEN', 1);
+console.log('Verses in Genesis 1:', chapter.numberOfVerses);
+```
+
+## Client Options
+
+You can customize the client with `FreeUseBibleApiOptions`:
+
+```ts
+import { FreeUseBibleApi } from 'free-use-bible-api';
+
+const api = new FreeUseBibleApi({
+    endpoint: 'https://bible.helloao.org/',
+    useCache: true,
+});
+```
+
+-   `endpoint`: Base API endpoint.
+-   `useCache`: Enables in-memory response caching (default: `true`).
+
+## API Methods
+
+### Translations
+
+-   `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()` 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?)`
+
+### Chapter Navigation Helpers
+
+-   `getNextChapter(chapter, endpoint?)`
+-   `getPreviousChapter(chapter, endpoint?)`
+
+### 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
+
+### Get a complete translation
+
+```ts
+const complete = await api.getCompleteTranslation('BSB');
+console.log(complete.translation.id);
+console.log(complete.books.length);
+```
+
+### Read a commentary chapter
+
+```ts
+const comm = await api.getCommentaryBookChapter('matthew_henry', 'GEN', 1);
+console.log(comm.book.name);
+```
+
+### Read a dataset chapter
+
+```ts
+const dataChapter = await api.getDatasetBookChapter(
+    'cross_references',
+    'JHN',
+    3
+);
+console.log(dataChapter.book.name);
+```
+
+### Navigate to next/previous chapter
+
+```ts
+const current = await api.getTranslationBookChapter('BSB', 'GEN', 1);
+
+const next = await api.getNextChapter(current);
+const previous = await api.getPreviousChapter(current);
+
+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
+
+-   `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/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`
+
+Example requests:
+
+```bash
+curl https://bible.helloao.org/api/available_translations.json
+curl https://bible.helloao.org/api/BSB/books.json
+curl https://bible.helloao.org/api/BSB/GEN/1.json
+curl https://bible.helloao.org/api/available_commentaries.json
+curl https://bible.helloao.org/api/available_datasets.json
+```
+
+## Error Handling
+
+Methods throw on non-2xx responses.
+
+A 404 response usually means one of the path values is invalid, for example:
+
+-   translation
+-   commentary
+-   dataset
+-   book
+-   chapter
+
+## Notes
+
+-   Uses the global `fetch` API.
+-   For Node.js, use a runtime that provides `fetch` (Node 18+ recommended) or polyfill it.

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
     );
   }
@@ -126,6 +141,98 @@ 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
+    );
+  }
+  /**
+   * 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.
+   */
+  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);
+  }
+  /**
+   * 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.
+   */
+  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,7 +245,23 @@ 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
     );
   }
@@ -259,6 +382,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);