@ambry/scripture 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ambry contributors
+
+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,3 +1,152 @@
-# Temporary Holding Version
+# @ambry/scripture
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ambry's 73 Bible books, canonical API codes, common aliases, reference parser, and scripture API client.
+The package has no runtime dependencies and includes ESM, CommonJS, and TypeScript declarations.
+The root export works offline without credentials; authenticated requests live in `@ambry/scripture/client`.
+Node.js 20 or newer is required for the client. The offline parser also works in modern browsers.
+
+## Install
+
+After the package has been published to npm:
+
+```sh
+npm install @ambry/scripture
+```
+
+Before publication, install a packed release directly:
+
+```sh
+npm install /path/to/ambry-scripture-0.1.0.tgz
+```
+
+## Books and reference parsing
+
+```ts
+import { scriptureBooks, parseScriptureReference, findScriptureReferences } from '@ambry/scripture';
+
+scriptureBooks.find((book) => book.code === 'joh');
+// { name: 'John', code: 'joh', aliases: ['Jn'] }
+
+parseScriptureReference('Jn. 3:16–18 GRK');
+// {
+//   book: 'John', bookCode: 'joh', chapter: 3,
+//   firstVerse: 16, lastVerse: 18, language: 'greek'
+// }
+
+parseScriptureReference('John 3'); // A chapter reference, without verse bounds.
+parseScriptureReference('Not a Bible reference'); // undefined
+
+findScriptureReferences('Read John 3:16 and Romans 8:28 GRK.');
+// Two references, both in Greek.
+
+findScriptureReferences('John 3:16 LAT, Romans 8:28 GRK');
+// John in Latin; Romans in Greek.
+```
+
+Each book keeps its `name`, `code`, and `aliases` together in `src/books.ts`.
+Canonical names, Ambry codes, and aliases are case insensitive. Periods and spacing in
+abbreviations are normalized, so `Jn. 3:16` and `1Jn4:8` are accepted.
+
+`parseScriptureReference` accepts a chapter, a single verse, or a same-chapter verse range.
+`findScriptureReferences` detects explicit chapter-and-verse references anywhere in text;
+chapter-only references are skipped. Duplicate references in the same language are returned once.
+Results follow their appearance in the input. Cross-chapter ranges and comma-separated verse lists
+are not supported.
+
+Both functions validate syntax and broad bounds (chapters 1–150, verses 1–176).
+They do not check whether a specific book/chapter/verse exists in Ambry's database.
+References use Ambry's book and chapter numbering, including its Psalm numbering.
+
+## Languages
+
+English is the default. Suffixes are case insensitive:
+
+| Language | Accepted suffixes | Ambry field |
+| --- | --- | --- |
+| English | `ENG`, `EN`, `ENGLISH` | `english_text` |
+| Greek | `GRK`, `GRC`, `GREEK` | `greek_text` |
+| Latin | `LAT`, `LA`, `LATIN` | `latin_text` |
+
+A suffix directly after a reference applies to that reference. A suffix at the end of a message
+also applies to references without their own suffix. `scriptureLanguages` exports the display labels
+and API text fields. The API supplies the text; the package does not bundle Bible translations.
+An unavailable language field remains unavailable rather than falling back to a different language.
+The API does not identify a particular English edition in its response metadata.
+
+## Consumer limits
+
+The parser allows up to 176 verses in a range by default. Detection returns up to 10 distinct references
+by default. Applications can set their own limits, independently of the Ambry dataset:
+
+```ts
+parseScriptureReference('John 3:16-18', { maxVerses: 20 });
+findScriptureReferences('John 3:16, Romans 8:28', { maxVerses: 20, maxReferences: 3 });
+```
+
+Limits must be positive safe integers; invalid options throw `RangeError`.
+
+## Authenticated API client
+
+```ts
+import { parseScriptureReference, scriptureLanguages } from '@ambry/scripture';
+import { fetchScripture } from '@ambry/scripture/client';
+
+const reference = parseScriptureReference('John 3:16 GRK');
+if (!reference) throw new Error('Invalid scripture reference.');
+
+const result = await fetchScripture(reference, {
+    apiKey: process.env.AMBRY_API_KEY!,
+    // baseUrl: 'https://api.ambry.church', // Default; override for your own API instance.
+});
+
+const language = scriptureLanguages[reference.language ?? 'english'];
+for (const verse of result.verses) {
+    console.log(verse[language.field] ?? 'Text unavailable in the requested language.');
+}
+```
+
+Keep API keys on your server. Obtain an Ambry developer key at
+`https://ambry.church/developers/api-keys`. The client uses bearer authentication and
+`GET /api/v1/bible-verses`, validates responses, and reads up to two 100-verse pages to retrieve
+a full chapter. It returns `{ verses, total }`; presentation, preview limits, and message splitting
+belong to the consumer. A single-verse request uses the API's `verse` filter.
+
+No results return an empty `verses` array. HTTP failures, malformed responses, and partially returned
+verse ranges throw an error. Requests time out after 15 seconds per page and refuse redirects;
+credentials and response bodies are not included in client-generated errors.
+The third argument accepts a fetch-compatible function for other runtimes or local verification.
+
+CommonJS is supported through the same exports:
+
+```js
+const { parseScriptureReference } = require('@ambry/scripture');
+const { fetchScripture } = require('@ambry/scripture/client');
+```
+
+## Build and release
+
+From the Ambry repository root:
+
+```sh
+pnpm install
+pnpm check:scripture
+pnpm build:scripture
+mkdir -p /tmp/ambry-scripture-release
+pnpm --dir packages/scripture pack --pack-destination /tmp/ambry-scripture-release
+```
+
+The build emits `dist/esm` and `dist/cjs`, each with JavaScript and declaration files.
+Only those outputs, this README, the MIT license, and package metadata are packed.
+Verify the tarball in a separate consumer project before publishing.
+
+To publish the reviewed tarball, sign into an npm account with access to the `@ambry` scope:
+
+```sh
+npm whoami --registry=https://registry.npmjs.org/
+npm publish /tmp/ambry-scripture-release/ambry-scripture-0.1.0.tgz --access public
+```
+
+Increment `packages/scripture/package.json` before subsequent releases and rebuild/repack.
+`prepack` also runs the build when lifecycle scripts are enabled.
+Keep the book list aligned with the API's OpenAPI book name/code enums; alias and parser changes
+can be released without changing the Go or Laravel applications.

package/dist/cjs/books.d.ts

@@ -0,0 +1,295 @@
+export declare const scriptureBooks: readonly [{
+    readonly name: "Genesis";
+    readonly code: "gen";
+    readonly aliases: readonly ["Gen"];
+}, {
+    readonly name: "Exodus";
+    readonly code: "exo";
+    readonly aliases: readonly ["Ex", "Exod"];
+}, {
+    readonly name: "Leviticus";
+    readonly code: "lev";
+    readonly aliases: readonly ["Lev"];
+}, {
+    readonly name: "Numbers";
+    readonly code: "num";
+    readonly aliases: readonly ["Num"];
+}, {
+    readonly name: "Deuteronomy";
+    readonly code: "deu";
+    readonly aliases: readonly ["Deut"];
+}, {
+    readonly name: "Joshua";
+    readonly code: "jos";
+    readonly aliases: readonly ["Josh"];
+}, {
+    readonly name: "Judges";
+    readonly code: "jdg";
+    readonly aliases: readonly ["Judg"];
+}, {
+    readonly name: "Ruth";
+    readonly code: "rut";
+    readonly aliases: readonly ["Ruth"];
+}, {
+    readonly name: "1 Samuel";
+    readonly code: "1sa";
+    readonly aliases: readonly ["1 Sam"];
+}, {
+    readonly name: "2 Samuel";
+    readonly code: "2sa";
+    readonly aliases: readonly ["2 Sam"];
+}, {
+    readonly name: "1 Kings";
+    readonly code: "1ki";
+    readonly aliases: readonly ["1 Kgs"];
+}, {
+    readonly name: "2 Kings";
+    readonly code: "2ki";
+    readonly aliases: readonly ["2 Kgs"];
+}, {
+    readonly name: "1 Chronicles";
+    readonly code: "1ch";
+    readonly aliases: readonly ["1 Chron"];
+}, {
+    readonly name: "2 Chronicles";
+    readonly code: "2ch";
+    readonly aliases: readonly ["2 Chron"];
+}, {
+    readonly name: "Ezra";
+    readonly code: "ezr";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Nehemiah";
+    readonly code: "neh";
+    readonly aliases: readonly ["Neh"];
+}, {
+    readonly name: "Tobit";
+    readonly code: "tob";
+    readonly aliases: readonly ["Tob"];
+}, {
+    readonly name: "Judith";
+    readonly code: "jth";
+    readonly aliases: readonly ["Jdt"];
+}, {
+    readonly name: "Esther";
+    readonly code: "est";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Job";
+    readonly code: "job";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Psalms";
+    readonly code: "psa";
+    readonly aliases: readonly ["Psalm", "Ps"];
+}, {
+    readonly name: "Proverbs";
+    readonly code: "pro";
+    readonly aliases: readonly ["Prov"];
+}, {
+    readonly name: "Ecclesiastes";
+    readonly code: "ecc";
+    readonly aliases: readonly ["Eccl"];
+}, {
+    readonly name: "Song of Songs";
+    readonly code: "son";
+    readonly aliases: readonly ["Song of Solomon", "Canticles"];
+}, {
+    readonly name: "Wisdom";
+    readonly code: "wis";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Sirach";
+    readonly code: "sir";
+    readonly aliases: readonly ["Ecclesiasticus"];
+}, {
+    readonly name: "Isaiah";
+    readonly code: "isa";
+    readonly aliases: readonly ["Isa"];
+}, {
+    readonly name: "Jeremiah";
+    readonly code: "jer";
+    readonly aliases: readonly ["Jer"];
+}, {
+    readonly name: "Lamentations";
+    readonly code: "lam";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Baruch";
+    readonly code: "bar";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Ezekiel";
+    readonly code: "eze";
+    readonly aliases: readonly ["Ezek"];
+}, {
+    readonly name: "Daniel";
+    readonly code: "dan";
+    readonly aliases: readonly ["Dan"];
+}, {
+    readonly name: "Hosea";
+    readonly code: "hos";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Joel";
+    readonly code: "joe";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Amos";
+    readonly code: "amo";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Obadiah";
+    readonly code: "oba";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Jonah";
+    readonly code: "jon";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Micah";
+    readonly code: "mic";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Nahum";
+    readonly code: "nah";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Habakkuk";
+    readonly code: "hab";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Zephaniah";
+    readonly code: "zep";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Haggai";
+    readonly code: "hag";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Zechariah";
+    readonly code: "zec";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Malachi";
+    readonly code: "mal";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "1 Maccabees";
+    readonly code: "1ma";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "2 Maccabees";
+    readonly code: "2ma";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Matthew";
+    readonly code: "mat";
+    readonly aliases: readonly ["Mt", "Matt"];
+}, {
+    readonly name: "Mark";
+    readonly code: "mar";
+    readonly aliases: readonly ["Mk"];
+}, {
+    readonly name: "Luke";
+    readonly code: "luk";
+    readonly aliases: readonly ["Lk"];
+}, {
+    readonly name: "John";
+    readonly code: "joh";
+    readonly aliases: readonly ["Jn"];
+}, {
+    readonly name: "Acts";
+    readonly code: "act";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Romans";
+    readonly code: "rom";
+    readonly aliases: readonly ["Rom"];
+}, {
+    readonly name: "1 Corinthians";
+    readonly code: "1co";
+    readonly aliases: readonly ["1 Cor"];
+}, {
+    readonly name: "2 Corinthians";
+    readonly code: "2co";
+    readonly aliases: readonly ["2 Cor"];
+}, {
+    readonly name: "Galatians";
+    readonly code: "gal";
+    readonly aliases: readonly ["Gal"];
+}, {
+    readonly name: "Ephesians";
+    readonly code: "eph";
+    readonly aliases: readonly ["Eph"];
+}, {
+    readonly name: "Philippians";
+    readonly code: "phi";
+    readonly aliases: readonly ["Phil"];
+}, {
+    readonly name: "Colossians";
+    readonly code: "col";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "1 Thessalonians";
+    readonly code: "1th";
+    readonly aliases: readonly ["1 Thess"];
+}, {
+    readonly name: "2 Thessalonians";
+    readonly code: "2th";
+    readonly aliases: readonly ["2 Thess"];
+}, {
+    readonly name: "1 Timothy";
+    readonly code: "1ti";
+    readonly aliases: readonly ["1 Tim"];
+}, {
+    readonly name: "2 Timothy";
+    readonly code: "2ti";
+    readonly aliases: readonly ["2 Tim"];
+}, {
+    readonly name: "Titus";
+    readonly code: "tit";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Philemon";
+    readonly code: "phm";
+    readonly aliases: readonly ["Philem"];
+}, {
+    readonly name: "Hebrews";
+    readonly code: "heb";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "James";
+    readonly code: "jam";
+    readonly aliases: readonly ["Jas"];
+}, {
+    readonly name: "1 Peter";
+    readonly code: "1pe";
+    readonly aliases: readonly ["1 Pet"];
+}, {
+    readonly name: "2 Peter";
+    readonly code: "2pe";
+    readonly aliases: readonly ["2 Pet"];
+}, {
+    readonly name: "1 John";
+    readonly code: "1jo";
+    readonly aliases: readonly ["1 Jn"];
+}, {
+    readonly name: "2 John";
+    readonly code: "2jo";
+    readonly aliases: readonly ["2 Jn"];
+}, {
+    readonly name: "3 John";
+    readonly code: "3jo";
+    readonly aliases: readonly ["3 Jn"];
+}, {
+    readonly name: "Jude";
+    readonly code: "jud";
+    readonly aliases: readonly [];
+}, {
+    readonly name: "Revelation";
+    readonly code: "rev";
+    readonly aliases: readonly ["Apocalypse"];
+}];
+export type ScriptureBook = (typeof scriptureBooks)[number];
+export type ScriptureBookCode = ScriptureBook['code'];

package/dist/cjs/books.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scriptureBooks = void 0;
+// Canonical names and codes from https://api.ambry.church/openapi.json.
+exports.scriptureBooks = [
+    { name: 'Genesis', code: 'gen', aliases: ['Gen'] },
+    { name: 'Exodus', code: 'exo', aliases: ['Ex', 'Exod'] },
+    { name: 'Leviticus', code: 'lev', aliases: ['Lev'] },
+    { name: 'Numbers', code: 'num', aliases: ['Num'] },
+    { name: 'Deuteronomy', code: 'deu', aliases: ['Deut'] },
+    { name: 'Joshua', code: 'jos', aliases: ['Josh'] },
+    { name: 'Judges', code: 'jdg', aliases: ['Judg'] },
+    { name: 'Ruth', code: 'rut', aliases: ['Ruth'] },
+    { name: '1 Samuel', code: '1sa', aliases: ['1 Sam'] },
+    { name: '2 Samuel', code: '2sa', aliases: ['2 Sam'] },
+    { name: '1 Kings', code: '1ki', aliases: ['1 Kgs'] },
+    { name: '2 Kings', code: '2ki', aliases: ['2 Kgs'] },
+    { name: '1 Chronicles', code: '1ch', aliases: ['1 Chron'] },
+    { name: '2 Chronicles', code: '2ch', aliases: ['2 Chron'] },
+    { name: 'Ezra', code: 'ezr', aliases: [] },
+    { name: 'Nehemiah', code: 'neh', aliases: ['Neh'] },
+    { name: 'Tobit', code: 'tob', aliases: ['Tob'] },
+    { name: 'Judith', code: 'jth', aliases: ['Jdt'] },
+    { name: 'Esther', code: 'est', aliases: [] },
+    { name: 'Job', code: 'job', aliases: [] },
+    { name: 'Psalms', code: 'psa', aliases: ['Psalm', 'Ps'] },
+    { name: 'Proverbs', code: 'pro', aliases: ['Prov'] },
+    { name: 'Ecclesiastes', code: 'ecc', aliases: ['Eccl'] },
+    {
+        name: 'Song of Songs',
+        code: 'son',
+        aliases: ['Song of Solomon', 'Canticles'],
+    },
+    { name: 'Wisdom', code: 'wis', aliases: [] },
+    { name: 'Sirach', code: 'sir', aliases: ['Ecclesiasticus'] },
+    { name: 'Isaiah', code: 'isa', aliases: ['Isa'] },
+    { name: 'Jeremiah', code: 'jer', aliases: ['Jer'] },
+    { name: 'Lamentations', code: 'lam', aliases: [] },
+    { name: 'Baruch', code: 'bar', aliases: [] },
+    { name: 'Ezekiel', code: 'eze', aliases: ['Ezek'] },
+    { name: 'Daniel', code: 'dan', aliases: ['Dan'] },
+    { name: 'Hosea', code: 'hos', aliases: [] },
+    { name: 'Joel', code: 'joe', aliases: [] },
+    { name: 'Amos', code: 'amo', aliases: [] },
+    { name: 'Obadiah', code: 'oba', aliases: [] },
+    { name: 'Jonah', code: 'jon', aliases: [] },
+    { name: 'Micah', code: 'mic', aliases: [] },
+    { name: 'Nahum', code: 'nah', aliases: [] },
+    { name: 'Habakkuk', code: 'hab', aliases: [] },
+    { name: 'Zephaniah', code: 'zep', aliases: [] },
+    { name: 'Haggai', code: 'hag', aliases: [] },
+    { name: 'Zechariah', code: 'zec', aliases: [] },
+    { name: 'Malachi', code: 'mal', aliases: [] },
+    { name: '1 Maccabees', code: '1ma', aliases: [] },
+    { name: '2 Maccabees', code: '2ma', aliases: [] },
+    { name: 'Matthew', code: 'mat', aliases: ['Mt', 'Matt'] },
+    { name: 'Mark', code: 'mar', aliases: ['Mk'] },
+    { name: 'Luke', code: 'luk', aliases: ['Lk'] },
+    { name: 'John', code: 'joh', aliases: ['Jn'] },
+    { name: 'Acts', code: 'act', aliases: [] },
+    { name: 'Romans', code: 'rom', aliases: ['Rom'] },
+    { name: '1 Corinthians', code: '1co', aliases: ['1 Cor'] },
+    { name: '2 Corinthians', code: '2co', aliases: ['2 Cor'] },
+    { name: 'Galatians', code: 'gal', aliases: ['Gal'] },
+    { name: 'Ephesians', code: 'eph', aliases: ['Eph'] },
+    { name: 'Philippians', code: 'phi', aliases: ['Phil'] },
+    { name: 'Colossians', code: 'col', aliases: [] },
+    { name: '1 Thessalonians', code: '1th', aliases: ['1 Thess'] },
+    { name: '2 Thessalonians', code: '2th', aliases: ['2 Thess'] },
+    { name: '1 Timothy', code: '1ti', aliases: ['1 Tim'] },
+    { name: '2 Timothy', code: '2ti', aliases: ['2 Tim'] },
+    { name: 'Titus', code: 'tit', aliases: [] },
+    { name: 'Philemon', code: 'phm', aliases: ['Philem'] },
+    { name: 'Hebrews', code: 'heb', aliases: [] },
+    { name: 'James', code: 'jam', aliases: ['Jas'] },
+    { name: '1 Peter', code: '1pe', aliases: ['1 Pet'] },
+    { name: '2 Peter', code: '2pe', aliases: ['2 Pet'] },
+    { name: '1 John', code: '1jo', aliases: ['1 Jn'] },
+    { name: '2 John', code: '2jo', aliases: ['2 Jn'] },
+    { name: '3 John', code: '3jo', aliases: ['3 Jn'] },
+    { name: 'Jude', code: 'jud', aliases: [] },
+    { name: 'Revelation', code: 'rev', aliases: ['Apocalypse'] },
+];

package/dist/cjs/client.d.ts

@@ -0,0 +1,18 @@
+import { type ScriptureBookCode } from './books.js';
+import type { ScriptureReference } from './references.js';
+export type AmbryScriptureConfig = {
+    apiKey: string;
+    baseUrl?: string;
+};
+export type ScriptureVerse = {
+    book_code: ScriptureBookCode;
+    chapter: number;
+    verse: number;
+    english_text?: string | null;
+    greek_text?: string | null;
+    latin_text?: string | null;
+};
+export declare function fetchScripture(reference: ScriptureReference, config: AmbryScriptureConfig, fetcher?: typeof fetch): Promise<{
+    verses: ScriptureVerse[];
+    total: number;
+}>;

package/dist/cjs/client.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchScripture = fetchScripture;
+const books_js_1 = require("./books.js");
+function validateReference(reference) {
+    if (!books_js_1.scriptureBooks.some((book) => book.code === reference.bookCode) ||
+        !Number.isInteger(reference.chapter) ||
+        reference.chapter < 1 ||
+        reference.chapter > 150) {
+        throw new Error('Enter a valid scripture book code and chapter.');
+    }
+    if (reference.firstVerse == null && reference.lastVerse == null)
+        return;
+    if (!Number.isInteger(reference.firstVerse) ||
+        !Number.isInteger(reference.lastVerse) ||
+        reference.firstVerse < 1 ||
+        reference.lastVerse > 176 ||
+        reference.lastVerse < reference.firstVerse) {
+        throw new Error('Enter a valid scripture verse or range.');
+    }
+}
+async function fetchScripture(reference, config, fetcher = fetch) {
+    validateReference(reference);
+    if (typeof config.apiKey !== 'string' || !config.apiKey.trim())
+        throw new Error('An Ambry API key is required.');
+    const baseUrl = new URL(config.baseUrl ?? 'https://api.ambry.church');
+    if (!['https:', 'http:'].includes(baseUrl.protocol) || baseUrl.username || baseUrl.password) {
+        throw new Error('Use an HTTP(S) Ambry base URL without embedded credentials.');
+    }
+    const verses = [];
+    let total = 0;
+    for (let page = 1; page <= 2; page++) {
+        const url = new URL('api/v1/bible-verses', baseUrl.href.replace(/\/?$/, '/'));
+        url.searchParams.set('book_code', reference.bookCode);
+        url.searchParams.set('chapter', String(reference.chapter));
+        if (reference.firstVerse === reference.lastVerse && reference.firstVerse != null)
+            url.searchParams.set('verse', String(reference.firstVerse));
+        url.searchParams.set('per_page', '100');
+        url.searchParams.set('page', String(page));
+        const response = await fetcher(url, {
+            headers: {
+                Authorization: `Bearer ${config.apiKey}`,
+                Accept: 'application/json',
+            },
+            signal: AbortSignal.timeout(15000),
+            redirect: 'error',
+        });
+        if (!response.ok)
+            throw new Error(`Ambry scripture request failed (HTTP ${response.status}).`);
+        const data = await response.json();
+        const result = data;
+        if (!result ||
+            !result.pagination ||
+            result.pagination.page !== page ||
+            result.pagination.per_page !== 100 ||
+            !Number.isInteger(result.pagination.total) ||
+            result.pagination.total < 0 ||
+            result.pagination.total > 176 ||
+            !Number.isInteger(result.pagination.total_pages) ||
+            result.pagination.total_pages < 0 ||
+            result.pagination.total_pages > 2 ||
+            (result.data != null && !Array.isArray(result.data))) {
+            throw new Error('Ambry returned an invalid scripture response.');
+        }
+        total = result.pagination.total;
+        for (const verse of result.data ?? []) {
+            if (!verse ||
+                verse.book_code !== reference.bookCode ||
+                verse.chapter !== reference.chapter ||
+                !Number.isInteger(verse.verse) ||
+                verse.verse < 1 ||
+                verse.verse > 176 ||
+                ['english_text', 'greek_text', 'latin_text'].some((field) => verse[field] != null && typeof verse[field] !== 'string') ||
+                (reference.firstVerse === reference.lastVerse &&
+                    reference.firstVerse != null &&
+                    verse.verse !== reference.firstVerse)) {
+                throw new Error('Ambry returned an invalid scripture verse.');
+            }
+            if (verses.some((saved) => saved.verse === verse.verse))
+                throw new Error('Ambry returned duplicate scripture verses.');
+            verses.push(verse);
+        }
+        if (page >= result.pagination.total_pages)
+            break;
+    }
+    if (verses.length !== total)
+        throw new Error('Ambry returned an incomplete scripture passage.');
+    const selected = verses
+        .sort((a, b) => a.verse - b.verse)
+        .filter((verse) => reference.firstVerse == null ||
+        (verse.verse >= reference.firstVerse && verse.verse <= reference.lastVerse));
+    if (reference.firstVerse != null &&
+        selected.length &&
+        selected.length !== reference.lastVerse - reference.firstVerse + 1) {
+        throw new Error('Ambry did not return every verse in the requested range.');
+    }
+    return { verses: selected, total: selected.length };
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,2 @@
+export { scriptureBooks, type ScriptureBook, type ScriptureBookCode } from './books.js';
+export { parseScriptureReference, findScriptureReferences, scriptureLanguages, type ScriptureLanguage, type ScriptureReference, type ParseScriptureOptions, type FindScriptureOptions, } from './references.js';