helloao-bible-api-client

Small TypeScript client for the HelloAO Free Use Bible API.

The API is public static JSON over HTTP. No API key is required.

Install

bun add helloao-bible-api-client

npm install helloao-bible-api-client

Usage

import { createHelloAoBibleClient } from "helloao-bible-api-client";

const bible = createHelloAoBibleClient();

const translations = await bible.getAvailableTranslations();
const books = await bible.getTranslationBooks("BSB");
const genesisOne = await bible.getTranslationChapter("BSB", "GEN", 1);
const commentaries = await bible.getAvailableCommentaries();
const datasets = await bible.getAvailableDatasets();

Methods that take translation, commentary, dataset, book, or profile IDs also accept response objects with an id field.

const { translations } = await bible.getAvailableTranslations();
const bsb = translations.find((translation) => translation.id === "BSB");

if (bsb) {
  const { books } = await bible.getTranslationBooks(bsb);
  const genesis = books.find((book) => book.id === "GEN");

  if (genesis) {
    await bible.getTranslationChapter(bsb, genesis, 1);
  }
}

Common Patterns

Pick a translation, then navigate by response objects:

const { translations } = await bible.getAvailableTranslations();
const bsb = translations.find((translation) => translation.id === "BSB");

if (!bsb) {
  throw new Error("Translation not found");
}

const { books } = await bible.getTranslationBooks(bsb);
const john = books.find((book) => book.id === "JHN");

if (!john) {
  throw new Error("Book not found");
}

const johnThree = await bible.getTranslationChapter(bsb, john, 3);

Fetch the same passage across multiple translations:

const translationIds = ["BSB", "WEB"];

const chapters = await Promise.all(
  translationIds.map((translation) =>
    bible.getTranslationChapter(translation, "JHN", 3)
  )
);

Load Bible text, commentary, and cross references for one passage:

const [chapter, commentary, crossReferences] = await Promise.all([
  bible.getTranslationChapter("BSB", "JHN", 3),
  bible.getCommentaryChapter("tyndale", "JHN", 3),
  bible.getDatasetChapter("open-cross-ref", "JHN", 3),
]);

Fetch a whole translation when building local search or offline indexes:

const completeBsb = await bible.getCompleteTranslation("BSB");

By default, requests go to https://bible.helloao.org/api. You can override the base URL or fetch implementation for tests, proxies, or local mirrors.

const bible = createHelloAoBibleClient({
  baseUrl: "https://bible.helloao.org/api",
  fetch: globalThis.fetch,
});

API

• getAvailableTranslations()
• getTranslationBooks(translation)
• getTranslationChapter(translation, book, chapter)
• getCompleteTranslation(translation)
• getAvailableCommentaries()
• getCommentaryBooks(commentary)
• getCommentaryChapter(commentary, book, chapter)
• getCommentaryProfiles(commentary)
• getCommentaryProfile(commentary, profile)
• getAvailableDatasets()
• getDatasetBooks(dataset)
• getDatasetChapter(dataset, book, chapter)
• request<T>(path)

The package exports TypeScript types for the translation, commentary, dataset, book, chapter, footnote, profile, and cross-reference response shapes, plus ID reference helper types.

Contributions

Issues and small pull requests are welcome.

Development

bun install
bun run test
bun run test:integration
bun run check
bun run build