npm package: @makecode/mecab-story-mapping
Description: A library for story mapping based on user input with Mecab morphological analysis for Node.js
Author: sung-min
Latest version: 1.0.1

# Mecab 스토리 매핑 라이브러리

이 라이브러리는 Node.js 환경에서 사용자의 입력을 형태소 분석하여 미리 정의된 스토리와 매핑하고, 매핑 결과에 따라 다양한 액션을 실행할 수 있는 기능을 제공합니다.

예를 들어, `테스트케이스`, `{testcase}`, `실행` 이라는 스토리가 있고, 사용자가 `테스트케이스가 abc인 것 실행해줘!` 라고 입력하면, 스토리에 설정된 액션이 실행되어 반환됩니다.

`현재 초기 버전으로 2.x 공식 버전을 준비하고 있습니다.`

## 주요 기능

- **형태소 분석**: `@makecode/mecab-analyzer`를 사용하여 입력된 텍스트를 분석합니다.
- **스토리 관리**: 스토리를 추가, 수정, 삭제, 조회할 수 있는 기능을 제공합니다.
- **변수 매핑**: 사용자 입력에서 추출된 변수를 스토리 템플릿에 매핑합니다.
- **유사도 계산**: Jaro-Winkler와 코사인 유사도 계산을 통해 입력과 스토리 간의 유사도를 분석합니다.
- **액션 실행**: URL 요청, 파일 읽기, 메시지 반환 등의 액션을 실행합니다.

## 설치

라이브러리를 설치하려면 다음 명령어를 실행하세요:

```bash
npm install @makecode/mecab-story-mapping
```

## 사용 방법

### 라이브러리 가져오기

라이브러리를 가져와서 사용할 수 있습니다:

```typescript
import {
  getStories,
  setStories,
  mecabStoryMapping,
  setStoryInsert,
  setStoryUpdate,
  setStoryDelete,
  isStoryItem,
} from '@makecode/mecab-story-mapping';
```

### 스토리 정의

먼저 스토리를 정의합니다. 각 스토리는 단어 목록과 액션을 포함하고 있습니다.

`주의! {변수} 변수에 해당하는 부분은 영어만 가능 (현재 버전)`

```typescript
setStoryInsert({
  words: ['{city}', '날씨'],
  actionType: 'url',
  actionValue: 'https://api.weather.com/{도시}',
});
```

### 사용자 입력 매핑

사용자가 입력한 내용을 분석하고, 미리 정의된 스토리와 매핑합니다.

```typescript
(async () => {
  const result = await mecabStoryMapping('광주 날씨 알려줘');
  console.log(result);
})();
```

### 전체 스토리 조회

정의된 모든 스토리를 조회할 수 있습니다.

```typescript
const allStories = getStories();
console.log(allStories);
```

### 변수 기반 URL 호출

사용자의 입력에서 추출한 변수로 URL 호출을 수행하는 예제입니다:

```typescript
setStories([
  {
    words: ['검색', '{keyword}'],
    actionType: 'url',
    actionValue: 'https://www.google.com/search?q={keyword}',
  },
]);

(async () => {
  const result = await mecabStoryMapping('검색 React');
  console.log(result);
  // 출력: { status: 'success', data: { type: 'url', result: 'https://www.google.com/search?q=React' } }
})();
```

### 파일 읽기 및 동적 변수 변환

로컬 파일의 내용을 읽고, 변수 매핑 결과를 반영합니다:

```typescript
setStories([
  {
    words: ['파일', '{filename}'],
    actionType: 'file',
    actionValue: './data/{filename}.txt',
  },
]);

(async () => {
  const result = await mecabStoryMapping('파일 sample');
  console.log(result);
  // 출력: { status: 'success', data: { type: 'file', result: '파일 내용...' } }
})();
```

## 주요 인터페이스 설명

### `Story` 인터페이스

스토리 정의에 사용되는 인터페이스는 아래와 같습니다:

```typescript
interface Story {
  words: string[]; // 스토리 템플릿 (고정 단어 및 변수 포함)
  actionType: 'url' | 'message' | 'file'; // 실행할 액션 타입
  actionValue: string | File; // 액션 실행에 필요한 값
  actionOption?: string; // 추가 옵션 (예: URL 호출 방식)
}
```

### 주요 API

| 함수명              | 설명                                                                   |
| ------------------- | ---------------------------------------------------------------------- |
| `setStories`        | 스토리를 초기화하거나 대량으로 설정합니다.                             |
| `getStories`        | 현재 저장된 모든 스토리를 반환합니다.                                  |
| `setStoryInsert`    | 새로운 스토리를 추가합니다.                                            |
| `setStoryUpdate`    | 특정 스토리를 수정합니다.                                              |
| `setStoryDelete`    | 특정 스토리를 삭제합니다.                                              |
| `isStoryItem`       | 입력된 단어 배열이 이미 저장된 스토리에 존재하는지 확인합니다.         |
| `mecabStoryMapping` | 사용자 입력을 분석하고, 가장 적합한 스토리와 매핑한 결과를 반환합니다. |

## 에러 처리

매핑 과정에서 발생할 수 있는 일반적인 에러는 아래와 같습니다:

- **`잘못된 요청입니다.`**: `mecabStoryMapping`에 잘못된 입력값이 제공된 경우 발생.
- **`변수 {변수명} cannot be resolved.`**: 사용자 입력에서 변수 매핑에 실패한 경우 발생.
- **`매핑되는 스토리가 없습니다.`**: 적합한 스토리를 찾을 수 없는 경우 반환.

각 에러 메시지를 기반으로 추가적인 처리를 구현할 수 있습니다.