biblesdk/README.md

Typescript client for Bible SDK API

# Bible SDK TypeScript Client

[![npm version](https://img.shields.io/npm/v/biblesdk.svg)](https://www.npmjs.com/package/biblesdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

TypeScript client for accessing Bible data and search functionality. This package provides a clean interface to our [REST API endpoints](https://biblesdk.com/docs) with full TypeScript support.

## 🚀 Features

- **📖 Bible Text Access** - Access Bible text through structured API endpoints with proper licensing and attribution
- **🔍 Strong's Concordance** - Get original language definitions, transliterations, and detailed concordance information for deeper study
- **🤖 Semantic Search** - Find relevant verses with natural language queries using AI-powered semantic search
- **🚀 Simple REST API** - Easy-to-use REST endpoints with JSON responses, no authentication required
- **📱 Full TypeScript Support** - Complete type definitions for all functions, parameters, and return types
- **⚡ Performance Optimized** - Includes LRU cache to reduce network calls and improve performance
- **🔄 Resilient** - Implements retry logic with timeouts and exponential backoff

## 📦 Installation

```bash
npm install biblesdk
```

## 🎯 Quick Start

```typescript
import { listBooks, getVerse, getSearchResults } from 'biblesdk';

// List all books in the Bible
const books = await listBooks();

// Get a specific range of verses
const verse = await getVerses('GEN', 1, [1, 2]);

// Search for verses using natural language
const results = await getSearchResults('love your neighbor');
```

## 📚 Reference
Please visit our [Complete SDK Guide](https://biblesdk.com/docs/sdk) for reference docs and a live try-it-out experience.

## 🔍 Use Cases

This SDK is perfect for building:

- **📱 Bible Apps** - Mobile applications for Bible study and reading
- **🎓 Educational Platforms** - Bible study courses and theological education
- **📖 Devotional Apps** - Daily devotional and spiritual growth applications
- **🔬 Research Tools** - Biblical research and analysis applications

## 📖 Bible Translation

This SDK provides access to the **NET Bible (New English Translation)** with comprehensive study notes. The NET Bible is copyrighted by Biblical Studies Press, L.L.C. and requires proper attribution for all uses.

### Copyright Requirements

When using this SDK to access NET Bible text, you must comply with the following requirements:

- **Attribution Required**: All uses of NET Bible text must include proper copyright attribution to Biblical Studies Press, L.L.C.
- **No Modification**: The NET Bible text may not be modified, altered, or changed in any way.
- **Commercial Use**: Commercial use of NET Bible text requires written permission from Biblical Studies Press, L.L.C.
- **Distribution Limits**: NET Bible text may not be distributed in printed form without permission.
- **Digital Use**: Digital use is permitted for personal study, research, and non-commercial applications.

## 🔧 Advanced Usage

### Book Codes

Use standard 3-letter book codes: `GEN` (Genesis), `EXO` (Exodus), `PSA` (Psalms), `MAT` (Matthew), `JHN` (John), etc. You can get the full list by calling `listBooks()`.

### Concordance Information

Add concordance information to any verse request to get Strong's definitions, original language information, and transliterations:

```typescript
const scriptureWithConcordanceInfo = await getPhrases('GEN', 1, [1, 2], true);
// Includes: strongs_number, strongs_type, transliteration, definition, hebrew_word, greek_word
```

### Semantic Search

The search endpoint uses AI-powered semantic search to find relevant verses based on meaning, not just exact text matches:

```typescript
// Search using natural language
const results = await getSearchResults('love your neighbor');
```

## 📚 Documentation

- **[Complete SDK Guide](https://biblesdk.com/docs/sdk)** - Interactive examples and detailed documentation
- **[API Documentation](https://biblesdk.com/docs)** - Complete REST API reference
- **[Home Page](https://biblesdk.com)** - Overview and features

## 🤝 Issues

Encountering some issue with the SDK or API? Please open an issue on our [Github Issues board](https://github.com/biblesdk/issues/issues).

## 📄 License

This SDK is provided free of charge for legitimate use. Users are responsible for complying with all applicable copyright laws. Rate limiting may be applied to ensure fair usage.

## 🔗 Links

- **Website**: https://biblesdk.com
- **API Docs**: https://biblesdk.com/docs
- **SDK Docs**: https://biblesdk.com/docs/sdk
- **npm Package**: https://www.npmjs.com/package/biblesdk
- **NET Bible Copyright**: https://netbible.com/copyright/

---

**NET Bible® Copyright Notice**: Scripture quotations are from the NET Bible® copyright ©1996, 2019 by Biblical Studies Press, L.L.C. [http://netbible.com](https://netbible.com/copyright/) All rights reserved.