free-use-bible-api 0.1.3 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 AO Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,139 +1,253 @@
-# Free Use Bible API
-
-The Free Use Bible API provides access to over 1000 Bible translations in hundreds of languages.
-
-This package is an auto-generated TypeScript and JavaScript client for the public API hosted at:
-
-- https://bible.helloao.org
-
-## Installation
-
-Install with your preferred package manager:
-
-```bash
-npm install free-use-bible-api
-```
-
-```bash
-pnpm add free-use-bible-api
-```
-
-```bash
-yarn add free-use-bible-api
-```
-
-## Quick Start
-
-Create a client and point it at the production API:
-
-```ts
-import { Configuration, FreeUseBibleApi } from 'free-use-bible-api';
-
-const config = new Configuration({
-	basePath: 'https://bible.helloao.org',
-});
-
-const api = new FreeUseBibleApi(config);
-```
-
-## Translation Usage Guide
-
-This section covers the most common translation flow:
-
-1. Get available translations.
-2. Pick a translation ID.
-3. Get books for that translation.
-4. Fetch a chapter.
-5. Optionally fetch the full translation payload.
-
-### 1. Get Available Translations
-
-```ts
-import { Configuration, FreeUseBibleApi } from 'free-use-bible-api';
-
-const api = new FreeUseBibleApi(
-	new Configuration({ basePath: 'https://bible.helloao.org' })
-);
-
-const result = await api.getAvailableTranslations();
-
-console.log('Total translations:', result.translations.length);
-console.log('First translation:', result.translations[0]);
-```
-
-### 2. Get Books For A Translation
-
-Use a translation ID from the previous step, for example `BSB`:
-
-```ts
-const books = await api.getTranslationBooks({
-	translation: 'BSB',
-});
-
-console.log('Books in translation:', books.books.length);
-console.log('First book:', books.books[0]);
-```
-
-### 3. Get A Translation Chapter
-
-Use a USFM book ID and chapter number:
-
-```ts
-import { BookId } from 'free-use-bible-api';
-
-const chapter = await api.getTranslationBookChapter({
-	translation: 'BSB',
-	book: BookId.GEN,
-	chapter: 1,
-});
-
-console.log('Chapter number:', chapter.chapter.number);
-console.log('Verse count:', chapter.numberOfVerses);
-```
-
-### 4. Get A Complete Translation
-
-Some workflows need the entire translation document in one call:
-
-```ts
-const complete = await api.getTranslationComplete({
-	translation: 'BSB',
-});
-
-console.log('Translation:', complete.translation.id);
-console.log('Book count:', complete.books.length);
-```
-
-## Direct HTTP Examples For Translations
-
-If you do not want to use the SDK, these translation endpoints are available directly:
-
-- GET `/api/available_translations.json`
-- GET `/api/{translation}/books.json`
-- GET `/api/{translation}/{book}/{chapter}.json`
-- GET `/api/{translation}/complete.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
-```
-
-## Error Handling
-
-A 404 response usually means one of these values is invalid:
-
-- translation
-- book
-- chapter
-
-Use available translations and books responses to drive your UI selections and reduce bad requests.
-
-## Notes
-
-- This client uses fetch under the hood.
-- In modern Node.js versions, fetch is available globally.
-- For custom environments, pass a custom fetch implementation in `Configuration`.
-
+# 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.