@jager-ai/holy-bible-api

v1.0.0

Published

5 months ago

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

0High
0Medium
0Low

jager-ai

bible bible-api korean-bible scripture verse holy-habit mvp-factory typescript

@mvp-factory/holy-bible-api

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

✨ 주요 기능

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

🚀 빠른 시작

설치

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

기본 사용법

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}`);
  });
}

📖 슬래시 명령어

자동 변환

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

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도 기억하세요."

슬래시 명령어 감지

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를 사용하는 경우:

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

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

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

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

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

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

검색 옵션

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

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

성경책 정보 조회

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');

주제별 구절

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']

📚 유틸리티 함수

텍스트 파싱

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

구절 검증

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

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

캐시 관리

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

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

🔧 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;
}

📋 예제 코드

성경 읽기 앱 통합

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);
  }
}

성경 검색 기능

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}`);
    });
  }
}

🐛 문제 해결

구절을 찾을 수 없는 경우

// 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"

성능 최적화

// 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권 구조 정보: 각 책의 장 수 및 약어
주제별 분류: 책별 주요 주제 태그
절기별 추천: 성탄절, 부활절 등 절기별 구절

🤝 기여하기

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

📄 라이센스

MIT License

🙏 크레딧

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

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