FHL Bible API - JavaScript SDK

信望愛聖經工具 (FHL) JavaScript SDK - A comprehensive Node.js client library for accessing the Faith, Hope, Love (FHL) Chinese Bible API.

Features

✅ Comprehensive Coverage: 217 books (66 canonical + Apocrypha + Apostolic Fathers)
✅ 50+ Bible Versions: Chinese (和合本, 新譯本, etc.), English (KJV, NIV, ESV), Taiwanese
✅ Apocrypha Support: Full access to deuterocanonical books (次經 101-115)
✅ Apostolic Fathers: Early Christian writings (使徒教父 201-217)
✅ Strong's Numbers: Original Hebrew/Greek word analysis
✅ Commentary Support: Access biblical commentaries (註釋)
✅ Simplified/Traditional: Support for both 簡體/繁體 Chinese
✅ Full-Text Search: Search verses across entire Bible or specific testaments
✅ Type Safety: Complete JSDoc type annotations
✅ Error Handling: Custom error classes for precise error management
✅ Modern ES Modules: Uses latest JavaScript features
✅ Tested: Comprehensive Jest test suite (35+ tests)

Installation

npm install fhl-bible-api

Or with yarn:

yarn add fhl-bible-api

📖 Documentation

• Quick Start Guide - Get started in 5 minutes
• Full Documentation - Complete documentation index
• Project Structure - Understand the codebase
• Examples - Practical usage examples
• Publishing Guide - For maintainers

Quick Start

import { FHLBibleClient } from 'fhl-bible-api';

// Create a client instance
const client = new FHLBibleClient({
  defaultVersion: 'unv',      // Default Bible version
  defaultSimplified: false,   // Use traditional Chinese by default
});

// Get a single verse (John 3:16 - 約翰福音 3:16)
const verse = await client.getVerse(43, 3, 16);
console.log(verse.text); // "神愛世人，甚至將他的獨生子賜給他們..."

// Get Apocrypha verse (Wisdom 1:1 - 智慧篇 1:1)
const wisdom = await client.getApocryphaVerse(105, 1, 1);
console.log(wisdom.text);

// Get Apostolic Fathers (Didache 1:1 - 十二使徒遺訓 1:1)
const didache = await client.getApostolicFathersVerse(212, 1, 1);
console.log(didache.text);

// Search for verses containing keyword
const results = await client.searchVerses('愛');
console.log(`Found ${results.length} verses`);

// Get entire chapter
const chapter = await client.getChapter(1, 1); // Genesis 1
console.log(`Genesis 1 has ${chapter.length} verses`);
defaultSimplified: false, // Traditional Chinese (default)
  timeout: 10000,         // Request timeout (ms)
  baseUrl: 'https://bible.fhl.net/json', // Optional: custom API URL
});

Get Single Verse

// Get John 3:16 in 和合本 (UNV)
const verse = await client.getVerse(43, 3, 16);

// Get with specific version (KJV)
const verseKJV = await client.getVerse(43, 3, 16, { 
  version: 'kjv' 
});

// Use simplified Chinese (简体中文)
const verseSimplified = await client.getVerse(43, 3, 16, {
  simplified: true
const client = new FHLBibleClient({
  defaultVersion: 'unv',  // 和合本 (default)
  timeout: 10000,         // Request timeout (ms)
  baseUrl: 'https://bible.fhl.net/json', // Optional: custom API URL
});

Get Single Verse

// Get John 3:16 in 和合本 (UNV)
const verse = await client.getVerse(43, 3, 16);

// Get with specific version (KJV)
const verseKJV = await client.getVerse(43, 3, 16, { 
  version: 'kjv' 
});

// Include Strong's numbers
const verseWithStrongs = await client.getVerse(43, 3, 16, { 
  includeStrongs: true 
});

console.log(verse);
// {
//   bookId: 43,
//   bookName: '約翰福音',
//   chapter: 3,
//   verse: 16,
//   text: '神愛世人...',
//   version: 'unv'
// }

Get Multiple Verses

// Get entire chapter
const chapter = await client.getChapter(19, 23); // Psalm 23

// Get verse range (John 3:16-18)
const verses = await client.getVerses(43, 3, {
  startVerse: 16,
  endVerse: 18
});

// Get with specific version
const versesNIV = await client.getVerses(43, 3, { 
  version: 'niv' 
});

Search Verses

// Search entire Bible
const results = await client.searchVerses('神愛世人');

// Search only New Testament
const ntResults = await client.searchVerses('love', { 
  testament: 'NT' 
});

// Search only Old Testament
const otResults = await client.searchVerses('以色列', { 
  testament: 'OT' 
});

// Limit results
const limitedResults = await client.searchVerses('耶穌', { 
  limit: 50 
});

console.log(results[0]);
// {
//   verse: { bookId: 43, chapter: 3, verse: 16, text: '...' },
//   reference: '約翰福音 3:16',
//   relevance: 1.0,
//   highlight: '神愛世人...'
// }

Get Word Parsing (Strong's Numbers)

// Get parsed words with Strong's numbers (requires version with Strong's support)
const parsed = await client.getVerseParsing(43, 3, 16);

console.log(parsed.words);
// [
//   {
//     position: 1,
//     word: '神',
//     strongsNumber: 'H430',
//     transliteration: 'elohim',
//     grammar: 'noun'
//   },
//   ...
// ]

Get Commentary

// Get all commentaries for a verse
const commentaries = await client.getCommentary(43, 3, 16);
// Use simplified Chinese
const simplifiedCommentary = await client.getCommentary(43, 3, 16, {
  simplified: true
});

console.log(commentaries[0]);
// {
//   bookId: 43,
//   chapter: 3,
//   verse: 16,
//   commentator: '馬太亨利',
//   text: '...',
//   language: 'zh'
// }

Apocrypha (次經)

// Get Tobit 1:1 (多俾亞傳)
const tobit = await client.getApocryphaVerse(101, 1, 1);

// Get Wisdom Chapter 1 (智慧篇第1章)
const wisdomChapter = await client.getApocryphaChapter(105, 1);

// Get Sirach 1:1 with simplified Chinese (德訓篇 简体)
const sirach = await client.getApocryphaVerse(106, 1, 1, {
  simplified: true
});

console.log(tobit);
// {
//   bookId: 101,
//   bookName: '多俾亞傳',
//   chapter: 1,
//   verse: 1,
//   text: '...',
//   version: 'apocrypha'
// }

Apostolic Fathers (使徒教父)

// Close client when done (cleanup resources) client.close();

// Get 1 Clement 1:1 (革利免前書)
const clement = await client.getApostolicFathersVerse(201, 1, 1);

// Get Didache Chapter 1 (十二使徒遺訓第1章)
const didacheChapter = await client.getApostolicFathersChapter(212, 1);

// Get Barnabas 1:1 (巴拿巴書)
const barnabas = await client.getApostolicFathersVerse(213, 1, 1);

console.log(didacheChapter[0]);
// {
//   bookId: 212,
//   bookName: '十二使徒遺訓',
//   chapter: 1,
//   verse: 1,
//   text: '...',
//   version: 'apostolic'
// }

Navigation

// Get previous/next verse info
const nav = await client.getNavigation(43, 3, 16);

console.log(nav);
// {
//   previous: { bookId: 43, chapter: 3, verse: 15 },
//   current: { bookId: 43, chapter: 3, verse: 16 },
//   next: { bookId: 43, chapter: 3, verse: 17 }
// }

Utility Methods

// Get detailed book information
const bookInfo = client.getBookInfo(43);
console.log(bookInfo);
// {
//   id: 43,
//   chinese: '約翰福音',
//   english: 'John',
//   abbreviation: 'Joh',
//   testament: 'NT'
// }

// Search books by name (Chinese or English)
const results = client.searchBookByName('約翰');
const resultsEn = client.searchBookByName('john');
console.log(results);
// [
//   { id: 43, name: '約翰福音', englishName: 'John', abbreviation: 'Joh' },
//   { id: 62, name: '約翰一書', englishName: '1 John', abbreviation: '1Jo' },
//   ...
// ]bookId: 43, chapter: 3, verse: 17 }
// }

Utility Methods

// Get all available Bible versions
const versions = client.getAvailableVersions();
console.log(versions.unv); // { name: '和合本', lang: 'zh', hasStrongs: true }

// Get all books
const allBooks = client.getBooks();

// Get books by testament
const otBooks = client.getBooks('OT');
const ntBooks = client.getBooks('NT');
const apocrypha = client.getBooks('APOCRYPHA');

// Check if version supports Strong's numbers
const hasStrongs = client.hasStrongsSupport('unv'); // true
const hasStrongsNIV = client.hasStrongsSupport('niv'); // false

Bible Book IDs

Canonical Books (1-66)

| ID | English | 中文 | ID | English | 中文 | |----|---------|------|----|---------|------| | 1 | Genesis | 創世記 | 40 | Matthew | 馬太福音 | | 2 | Exodus | 出埃及記 | 41 | Mark | 馬可福音 | | 3 | Leviticus | 利未記 | 42 | Luke | 路加福音 | | 19 | Psalms | 詩篇 | 43 | John | 約翰福音 | | 23 | Isaiah | 以賽亞書 | 45 | Romans | 羅馬書 | | ... | ... | ... | 66 | Revelation | 啟示錄 |

Apocrypha (101-115)

| ID | English | 中文 | |----|---------|------| | 101 | Tobit | 多俾亞傳 | | 102 | Judith | 友弟德傳 | | 103 | 1 Maccabees | 瑪加伯上 | | 105 | Wisdom | 智慧篇 | | 106 | Sirach | 德訓篇 |

Apostolic Fathers (201-217)

| ID | English | 中文 | |----|---------|------| | 201 | 1 Clement | 革利免前書 | | 212 | Didache | 十二使徒遺訓 | | 213 | Barnabas | 巴拿巴書 |

See src/constants.js for complete list.

Available Bible Versions

Chinese Versions

• unv - 和合本 (Union Version) ⭐ Has Strong's
• cunp - 和合本上帝版
• cuvs - 和合本簡體
• ncv - 新譯本
• tev - 現代中文譯本
• csb - 聖經當代譯本
• lzz - 呂振中譯本

English Versions

• kjv - King James Version ⭐ Has Strong's
• niv - New International Version
• esv - English Standard Version
• nasb - New American Standard Bible
• web - World English Bible ⭐ Has Strong's

Other Languages

• taigi - 台語羅馬字
• peh - 台語漢字

See src/constants.js for complete list.

Error Handling

The SDK provides custom error classes for precise error handling:

import { 
  ValidationError, 
  NetworkError, 
  NotFoundError,
  ServerError 
} from 'fhl-bible-api';

try {
  const verse = await client.getVerse(999, 1, 1); // Invalid book ID
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
    console.error('Details:', error.details);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found:', error.resource);
  }
}

Error Types

• FHLAPIError - Base error class
• ValidationError - Invalid input parameters
• NetworkError - Network/HTTP request failures
• NotFoundError - Resource not found (404)
• ServerError - Server errors (5xx)
• RateLimitError - Rate limit exceeded (429)
• ParseError - Response parsing errors

Examples

For more detailed examples, see the examples/ directory:

• examples.js - Basic usage examples (verses, chapters, search)
• examples-new-features.js - Advanced features (Apocrypha, word parsing, commentary)
• demo.js - Interactive demonstration of main features

Run examples:

node examples/examples.js
node examples/examples-new-features.js
node examples/demo.js

Development

Setup

# Clone repository
git clone https://github.com/yourusername/fhl-bible-api.git
cd fhl-bible-api

# Install dependencies
npm install

Scripts

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix lint issues
npm run lint:fix

# Format code
npm run format

# Format check
npm run format:check

Testing

The SDK includes comprehensive Jest tests with mocking:

npm test

Expected output:

PASS  tests/client.test.js
  ✓ should create instance with default options
  ✓ should fetch a single verse successfully
  ✓ should throw ValidationError for invalid book ID
  ...

Test Suites: 1 passed, 1 total
Tests:       20 passed, 20 total
Coverage:    85%

Code Quality

This project follows industry best practices:

• ✅ ESLint with @eslint/js configuration
• ✅ Prettier for consistent formatting
• ✅ JSDoc for complete type documentation
• ✅ Husky for pre-commit hooks
• ✅ lint-staged for automatic linting
• ✅ Jest with 80%+ coverage requirement

License

MIT License - see LICENSE file for details.

Attribution

This SDK accesses the 信望愛聖經工具 (Faith, Hope, Love Bible Tools) API provided by Taiwan Bible Society.

Please respect FHL's terms of service when using this SDK. Consider donating to support their ministry if you use this extensively.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 FHL Website: https://bible.fhl.net/

Changelog

v1.0.0 (2026-01-21)

• ✨ Initial release
• ✅ Complete API coverage (verses, search, parsing, commentary, navigation)
• ✅ 217 books supported (canonical + Apocrypha + Apostolic Fathers)
• ✅ 50+ Bible versions
• ✅ Strong's number support
• ✅ Comprehensive test suite
• ✅ Full JSDoc type annotations

Made with ❤️ for Bible study and research