oasis-chat 0.2.11 → 0.3.0

package/README.md

@@ -2,6 +2,20 @@
 
 `createButton`을 제공하는 가벼운 바닐라 JS 채팅 버튼 컴포넌트입니다. React와 Vue를 위한 wrapper 컴포넌트도 제공됩니다.
 
+**현재 버전:** `0.3.0`
+
+## 주요 기능
+
+- 💬 **실시간 스트리밍 채팅**: SSE(Server-Sent Events)를 통한 실시간 응답 스트리밍
+- 🔐 **자동 로그인**: 계정 정보 제공 시 버튼 생성과 동시에 자동 로그인
+- 🎨 **반응형 UI**: 모던하고 세련된 사용자 인터페이스
+- 🔄 **토글 패널**: 버튼 클릭으로 채팅 패널 열기/닫기
+- 📱 **외부 클릭 감지**: 패널 외부 클릭 시 자동으로 패널 닫기
+- 📝 **메시지 히스토리**: 이전 대화 기록 관리
+- 🚀 **다중 프레임워크 지원**: Vanilla JS, React, Vue 지원
+- 📦 **TypeScript 지원**: 완전한 TypeScript 타입 정의 제공
+- 🎯 **경량화**: 최소한의 의존성으로 가벼운 번들 사이즈
+
 ## 설치
 
 ```bash
@@ -12,6 +26,13 @@ npm install oasis-chat
 
 이 라이브러리는 내부적으로 [axios](https://axios-http.com/)를 사용합니다. axios는 자동으로 설치됩니다.
 
+### Peer Dependencies
+
+React 또는 Vue를 사용하는 경우, 해당 프레임워크가 프로젝트에 설치되어 있어야 합니다:
+
+- **React**: `^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || >=20.0.0`
+- **Vue**: `^3.0.0`
+
 ## 프록시 설정
 
 이 라이브러리는 `/oasis` 경로로 API 요청을 보냅니다. CORS 문제를 해결하기 위해 프로젝트의 개발 서버나 프록시에서 `/oasis` 경로를 프록시하도록 설정해야 합니다.
@@ -29,11 +50,11 @@ export default {
         target: 'https://oasis-dev.haiqv.ai',
         changeOrigin: true,
         secure: true,
-        rewrite: (path) => path.replace(/^\/oasis/, '/api'),
+        rewrite: path => path.replace(/^\/oasis/, '/api'),
       },
     },
   },
-};
+}
 ```
 
 #### Next.js
@@ -47,16 +68,16 @@ module.exports = {
         source: '/oasis/:path*',
         destination: 'https://oasis-dev.haiqv.ai/api/:path*',
       },
-    ];
+    ]
   },
-};
+}
 ```
 
 #### Create React App
 
 ```javascript
 // src/setupProxy.js (또는 package.json에 "proxy" 설정)
-const { createProxyMiddleware } = require('http-proxy-middleware');
+const { createProxyMiddleware } = require('http-proxy-middleware')
 
 module.exports = function (app) {
   app.use(
@@ -67,9 +88,9 @@ module.exports = function (app) {
       pathRewrite: {
         '^/oasis': '/api',
       },
-    })
-  );
-};
+    }),
+  )
+}
 ```
 
 ## 사용 예시
@@ -79,7 +100,7 @@ module.exports = function (app) {
 React 프로젝트에서 사용할 때는 wrapper 컴포넌트를 사용하면 CSS를 별도로 import할 필요가 없습니다.
 
 ```tsx
-import { OasisButton } from 'oasis-chat/react';
+import { OasisButton } from 'oasis-chat/react'
 
 function App() {
   return (
@@ -88,7 +109,7 @@ function App() {
       password="your-password"
       assistant_uuid="your-assistant-uuid"
     />
-  );
+  )
 }
 ```
 
@@ -98,7 +119,7 @@ Vue 프로젝트에서 사용할 때도 wrapper 컴포넌트를 사용하면 CSS
 
 ```vue
 <script setup>
-import { OasisButton } from 'oasis-chat/vue';
+import { OasisButton } from 'oasis-chat/vue'
 </script>
 
 <template>
@@ -115,25 +136,65 @@ import { OasisButton } from 'oasis-chat/vue';
 바닐라 JavaScript나 다른 프레임워크에서 사용할 때는 CSS를 수동으로 import해야 합니다.
 
 ```js
-import { createButton } from 'oasis-chat';
-import 'oasis-chat/style.css'; // CSS 파일 import 필요
+import { createButton } from 'oasis-chat'
+import 'oasis-chat/style.css' // CSS 파일 import 필요
 
 const btn = createButton({
   account_id: 'your-account-id',
   password: 'your-password',
   assistant_uuid: 'your-assistant-uuid',
-});
+})
 
-document.body.appendChild(btn);
+document.body.appendChild(btn)
 ```
 
 **참고**: React나 Vue wrapper를 사용할 때는 CSS를 별도로 import할 필요가 없습니다. wrapper 컴포넌트 내부에서 자동으로 CSS가 포함됩니다.
 
-## Props
+## API
+
+### `createButton(options)`
+
+채팅 버튼을 생성하고 반환합니다.
+
+#### Parameters
+
+- `options.account_id` (string, 선택): 로그인에 사용할 계정 ID. 제공된 경우 버튼 생성 시 자동으로 로그인을 시도합니다.
+- `options.password` (string, 선택): 로그인에 사용할 비밀번호. `account_id`와 함께 제공되어야 합니다.
+- `options.assistant_uuid` (string, 필수): 채팅에 사용할 어시스턴트 UUID
 
-- `account_id` (string, 필수): 로그인에 사용할 계정 ID
-- `password` (string, 필수): 로그인에 사용할 비밀번호
-- `assistant_uuid` (string, 필수): 어시스턴트 UUID
+#### Returns
+
+- `HTMLElement`: 생성된 버튼 컨테이너 요소
+
+#### Notes
+
+- `account_id`와 `password`를 제공하지 않으면 버튼이 생성되지만 로그인은 수행되지 않습니다.
+- 버튼은 싱글톤 패턴으로 관리되며, 여러 번 호출해도 하나의 인스턴스만 존재합니다.
+- 버튼 클릭 시 채팅 패널이 토글됩니다.
+
+### React 컴포넌트: `OasisButton`
+
+#### Props
+
+```typescript
+interface OasisButtonProps {
+  account_id: string
+  password: string
+  assistant_uuid: string
+}
+```
+
+### Vue 컴포넌트: `OasisButton`
+
+#### Props
+
+```typescript
+{
+  account_id: string
+  password: string
+  assistant_uuid: string
+}
+```
 
 ## 개발/빌드
 
@@ -149,6 +210,61 @@ npm run build:lib     # 라이브러리 빌드 (Vanilla JS, React, Vue 모두
 - `vue/index.*.js` - Vue wrapper 버전
 - `oasis-chat.css` - 스타일시트
 
+## 브라우저 호환성
+
+이 라이브러리는 다음 브라우저를 지원합니다:
+
+- Chrome (최신 2 버전)
+- Firefox (최신 2 버전)
+- Safari (최신 2 버전)
+- Edge (최신 2 버전)
+
+**최소 요구사항:**
+
+- ES2015+ 지원
+- Fetch API 또는 axios를 통한 HTTP 요청 지원
+- Server-Sent Events (SSE) 지원
+
+## 문제 해결
+
+### CORS 오류
+
+CORS 오류가 발생하는 경우, 프록시 설정 섹션을 참고하여 개발 서버에 프록시를 설정하세요.
+
+### CSS가 적용되지 않음
+
+Vanilla JS를 사용하는 경우 CSS를 명시적으로 import해야 합니다:
+
+```js
+import 'oasis-chat/style.css'
+```
+
+React나 Vue wrapper를 사용하는 경우 자동으로 CSS가 포함되므로 별도 import가 필요 없습니다.
+
+### 로그인 실패
+
+`account_id`와 `password`가 올바르게 제공되었는지 확인하세요. 네트워크 탭에서 API 요청이 제대로 전송되는지 확인할 수 있습니다.
+
+### 스트리밍 응답이 작동하지 않음
+
+브라우저가 Server-Sent Events (SSE)를 지원하는지 확인하세요. 최신 브라우저는 모두 SSE를 지원합니다.
+
+### React/Vue 컴포넌트가 렌더링되지 않음
+
+필수 peer dependencies가 설치되어 있는지 확인하세요:
+
+```bash
+# React 사용 시
+npm install react react-dom
+
+# Vue 사용 시
+npm install vue
+```
+
+## 기여하기
+
+버그 리포트나 기능 제안은 GitHub Issues를 통해 제출해주세요.
+
 ## 라이선스
 
 MIT