@jager-ai/holy-bible-api/README.md

성경 구절 검색 및 슬래시 명령어 지원 API 모듈

# @mvp-factory/holy-bible-api

한국어 성경 구절 검색 및 슬래시 명령어 지원 API 모듈

## ✨ 주요 기능

- 📖 **성경 66권 완벽 지원**: 구약 39권, 신약 27권 전체 지원
- 🔍 **성경 구절 검색**: 단일 구절 및 범위 구절 검색
- ⚡ **슬래시 명령어**: `/갈2:20`, `/요3:16-17` 형식 자동 변환
- 📚 **120+ 핵심 구절 내장**: 주요 성경 구절 즉시 사용 가능
- 🎯 **정확한 약어 매핑**: 한국 교회 표준 약어 지원
- 💾 **캐싱 시스템**: 빠른 응답을 위한 구절 캐싱
- 🌐 **API 연동 지원**: 외부 성경 API 연동 가능
- 🚀 **TypeScript 지원**: 완전한 타입 정의

## 🚀 빠른 시작

### 설치

```bash
npm install @mvp-factory/holy-bible-api
```

### 기본 사용법

```typescript
import { createBibleEngine } from '@mvp-factory/holy-bible-api';

// Bible engine 생성
const bible = createBibleEngine();

// 성경 구절 검색
const result = await bible.searchVerses('요한복음 3:16');
if (result.success && result.verses) {
  console.log(result.verses[0].text);
  // "하나님이 세상을 이처럼 사랑하사..."
}

// 범위 구절 검색
const rangeResult = await bible.searchVerses('시편 23:1-3');
if (rangeResult.success && rangeResult.verses) {
  rangeResult.verses.forEach(verse => {
    console.log(`${verse.verse}. ${verse.text}`);
  });
}
```

## 📖 슬래시 명령어

### 자동 변환

텍스트 내의 슬래시 명령어를 자동으로 성경 구절로 변환합니다:

```typescript
import { BibleVerseEngine } from '@mvp-factory/holy-bible-api';

const bible = BibleVerseEngine.getInstance();

const text = "오늘의 말씀은 /갈2:20 입니다. 또한 /요3:16도 기억하세요.";
const processed = await bible.processSlashCommands(text);

console.log(processed);
// "오늘의 말씀은 내가 그리스도와 함께 십자가에 못 박혔나니...
// - 갈라디아서 2:20 입니다. 또한 하나님이 세상을 이처럼 사랑하사...
// - 요한복음 3:16도 기억하세요."
```

### 슬래시 명령어 감지

```typescript
const commands = bible.detectSlashCommands("말씀 /롬8:28 과 /빌4:13 참조");
console.log(commands);
// [
//   { match: '/롬8:28', reference: '롬8:28', startIndex: 3, endIndex: 10 },
//   { match: '/빌4:13', reference: '빌4:13', startIndex: 14, endIndex: 21 }
// ]
```

## 🔤 지원하는 성경책 약어

### 구약 (39권)
```
창(창세기), 출(출애굽기), 레(레위기), 민(민수기), 신(신명기)
수(여호수아), 삿(사사기), 룻(룻기), 삼상(사무엘상), 삼하(사무엘하)
왕상(열왕기상), 왕하(열왕기하), 대상(역대상), 대하(역대하)
스(에스라), 느(느헤미야), 에(에스더), 욥(욥기), 시(시편)
잠(잠언), 전(전도서), 아(아가), 사(이사야), 렘(예레미야)
애(예레미야 애가), 겔(에스겔), 단(다니엘), 호(호세아)
욜(요엘), 암(아모스), 옵(오바댜), 욘(요나), 미(미가)
나(나훔), 합(하박국), 습(스바냐), 학(학개), 슥(스가랴), 말(말라기)
```

### 신약 (27권)
```
마(마태복음), 막(마가복음), 눅(누가복음), 요(요한복음)
행(사도행전), 롬(로마서), 고전(고린도전서), 고후(고린도후서)
갈(갈라디아서), 엡(에베소서), 빌(빌립보서), 골(골로새서)
살전(데살로니가전서), 살후(데살로니가후서)
딤전(디모데전서), 딤후(디모데후서), 딛(디도서), 몬(빌레몬서)
히(히브리서), 약(야고보서), 벧전(베드로전서), 벧후(베드로후서)
요일(요한일서), 요이(요한이서), 요삼(요한삼서), 유(유다서), 계(요한계시록)
```

## 🛠️ 고급 사용법

### API 엔드포인트 설정

외부 성경 API를 사용하는 경우:

```typescript
const bible = createBibleEngine('https://api.mybible.com/verse');

// 또는
bible.setApiEndpoint('https://api.mybible.com/verse');
```

### 전체 성경 데이터베이스 설정

서버 사이드에서 전체 성경 데이터를 로드하는 경우:

```typescript
import { BibleVerseEngine } from '@mvp-factory/holy-bible-api';

const bible = BibleVerseEngine.getInstance();
const fullDatabase = await loadBibleDatabase(); // 31,000+ 구절
bible.setFullVerseDatabase(fullDatabase);
```

### 검색 옵션

```typescript
const options = {
  includeHeadings: true,    // 소제목 포함 (기본: true)
  maxVerses: 10,           // 최대 구절 수 (기본: 20)
  cacheEnabled: true       // 캐싱 사용 (기본: true)
};

const result = await bible.searchVerses('시편 119:1-10', options);
```

### 성경책 정보 조회

```typescript
import { getBibleBook, getBooksByTestament } from '@mvp-factory/holy-bible-api';

// 특정 책 정보
const book = getBibleBook('롬');
console.log(book);
// { name: '로마서', abbr: '롬', chapters: 16, testament: 'new' }

// 구약/신약별 책 목록
const oldTestament = getBooksByTestament('old');
const newTestament = getBooksByTestament('new');
```

### 주제별 구절

```typescript
import { BIBLE_THEMES, SEASONAL_VERSES } from '@mvp-factory/holy-bible-api';

// 책별 주제
console.log(BIBLE_THEMES['시편']);
// ['찬양', '기도', '고백', '감사']

// 절기별 추천 구절
console.log(SEASONAL_VERSES['성탄절']);
// ['누가복음 2:11', '마태복음 1:23', '요한복음 1:14']
```

## 📚 유틸리티 함수

### 텍스트 파싱

```typescript
import { 
  parseBibleText, 
  extractBibleReferences,
  containsBibleVerse 
} from '@mvp-factory/holy-bible-api';

// 소제목 분리
const parsed = parseBibleText('[사랑의 하나님] 하나님은 사랑이시라');
console.log(parsed.heading); // '사랑의 하나님'
console.log(parsed.text);    // '하나님은 사랑이시라'

// 성경 구절 추출
const refs = extractBibleReferences('오늘 말씀은 요 3:16과 롬 8:28입니다');
console.log(refs); // ['요 3:16', '롬 8:28']

// 성경 구절 포함 확인
const hasVerse = containsBibleVerse('갈라디아서 2장 20절을 보세요');
console.log(hasVerse); // true
```

### 구절 검증

```typescript
// 유효한 구절 형식 확인
const isValid = bible.isValidReference('요한복음 3:16');
console.log(isValid); // true

// 지원하는 책 목록
const books = bible.getAvailableBooks();
console.log(books); // ['창', '출', '레', ...]
```

### 캐시 관리

```typescript
// 캐시 크기 확인
console.log(bible.getCacheSize()); // 120 (기본 핵심 구절)

// 캐시 초기화
bible.clearCache();
```

## 🔧 TypeScript 타입

```typescript
import type { 
  BibleVerse, 
  BibleApiResponse,
  ParsedBibleReference 
} from '@mvp-factory/holy-bible-api';

// 성경 구절 타입
interface BibleVerse {
  reference: string;      // "요한복음 3:16"
  book_full: string;      // "요한복음"
  chapter: number;        // 3
  verse: number;          // 16
  text: string;          // "하나님이 세상을..."
  heading?: string;       // 소제목 (선택)
}

// API 응답 타입
interface BibleApiResponse {
  success: boolean;
  verses?: BibleVerse[];
  error?: string;
  query?: string;
}
```

## 📋 예제 코드

### 성경 읽기 앱 통합

```typescript
import { createBibleEngine } from '@mvp-factory/holy-bible-api';

class BibleReader {
  private bible = createBibleEngine();
  
  async displayDailyVerse() {
    const today = new Date().toLocaleDateString('ko-KR');
    const verse = await this.bible.searchVerses('요한복음 3:16');
    
    if (verse.success && verse.verses) {
      console.log(`[${today}의 말씀]`);
      console.log(this.bible.formatVerse(verse.verses[0]));
    }
  }
  
  async processUserInput(text: string) {
    // 슬래시 명령어 자동 변환
    return await this.bible.processSlashCommands(text);
  }
}
```

### 성경 검색 기능

```typescript
async function searchBible(query: string) {
  const bible = createBibleEngine();
  
  // 먼저 정확한 구절 검색
  let result = await bible.searchVerses(query);
  
  if (!result.success) {
    // 실패 시 비슷한 구절 제안
    console.log('검색 실패:', result.error);
    console.log('제안:', result.suggestions);
  } else {
    // 검색 결과 표시
    result.verses?.forEach(verse => {
      console.log(`${verse.reference}: ${verse.text}`);
    });
  }
}
```

## 🐛 문제 해결

### 구절을 찾을 수 없는 경우

```typescript
// 1. 약어가 올바른지 확인
import { BIBLE_ABBREVIATIONS } from '@mvp-factory/holy-bible-api';
console.log(BIBLE_ABBREVIATIONS); // 지원 약어 목록

// 2. 참조 형식 확인
// 올바른 형식: "책명 장:절" 또는 "책명 장:절-절"
// 예: "요 3:16", "시 23:1-6"

// 3. 정규화 테스트
import { normalizeBibleReference } from '@mvp-factory/holy-bible-api';
console.log(normalizeBibleReference('롬1:1')); // "로마서 1:1"
```

### 성능 최적화

```typescript
// 1. 캐싱 활용
const options = { cacheEnabled: true };

// 2. 범위 제한
const options = { maxVerses: 10 }; // 큰 범위 검색 시 제한

// 3. 자주 사용하는 구절은 미리 로드
const commonVerses = ['요 3:16', '시 23:1', '롬 8:28'];
for (const ref of commonVerses) {
  await bible.searchVerses(ref);
}
```

## 📦 내장 데이터

- **120+ 핵심 구절**: 자주 사용되는 주요 성경 구절
- **66권 구조 정보**: 각 책의 장 수 및 약어
- **주제별 분류**: 책별 주요 주제 태그
- **절기별 추천**: 성탄절, 부활절 등 절기별 구절

## 🤝 기여하기

1. 이 저장소를 Fork 하세요
2. 새로운 기능 브랜치를 생성하세요 (`git checkout -b feature/AmazingFeature`)
3. 변경 사항을 커밋하세요 (`git commit -m 'Add some AmazingFeature'`)
4. 브랜치에 Push 하세요 (`git push origin feature/AmazingFeature`)
5. Pull Request를 열어주세요

## 📄 라이센스

MIT License

## 🙏 크레딧

이 모듈은 Holy Habit 프로젝트의 성경 API 시스템에서 추출되었습니다.

---

**@mvp-factory/holy-bible-api** - 한국어 성경 구절 API 모듈 📖✨