oasis-chat-button 0.2.0

package/README.md

@@ -0,0 +1,265 @@
+# Oasis Chat
+
+`createButton`을 제공하는 가벼운 바닐라 JS 채팅 버튼 컴포넌트입니다. React와 Vue를 위한 wrapper 컴포넌트도 제공됩니다.
+
+## 설치
+
+```bash
+npm install oasis-chat-button
+```
+
+### 의존성
+
+이 라이브러리는 내부적으로 [axios](https://axios-http.com/)를 사용합니다. axios는 자동으로 설치됩니다.
+
+### Peer Dependencies
+
+React 또는 Vue를 사용하는 경우, 해당 프레임워크가 프로젝트에 설치되어 있어야 합니다:
+
+- **React**: `^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.1 || ^19.1.2 || ^19.2.3 || >=19.3.0 || >=20.0.0`
+- **Vue**: `^3.0.0`
+
+**보안 참고사항**: React 19.0.0, 19.1.0, 19.1.1, 19.2.0, 19.2.1 버전은 CVE-2025-55182 (React2Shell) 취약점이 있어 사용하지 않습니다. 반드시 패치된 버전(19.0.1, 19.1.2, 19.2.2 이상, 권장: 19.2.3 이상)을 사용해주세요.
+
+## 프록시 설정
+
+이 라이브러리는 `/oasis` 경로로 API 요청을 보냅니다. CORS 문제를 해결하기 위해 프로젝트의 개발 서버나 프록시에서 `/oasis` 경로를 프록시하도록 설정해야 합니다.
+
+### 개발 서버 프록시 설정
+
+#### Vite
+
+```javascript
+// vite.config.js
+export default {
+  server: {
+    proxy: {
+      '/oasis': {
+        target: 'https://oasis-dev.haiqv.ai',
+        changeOrigin: true,
+        secure: true,
+        rewrite: path => path.replace(/^\/oasis/, '/api'),
+      },
+    },
+  },
+}
+```
+
+#### Next.js
+
+```javascript
+// next.config.js
+module.exports = {
+  async rewrites() {
+    return [
+      {
+        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')
+
+module.exports = function (app) {
+  app.use(
+    '/oasis',
+    createProxyMiddleware({
+      target: 'https://oasis-dev.haiqv.ai',
+      changeOrigin: true,
+      pathRewrite: {
+        '^/oasis': '/api',
+      },
+    }),
+  )
+}
+```
+
+## 사용 예시
+
+### React
+
+React 프로젝트에서 사용할 때는 wrapper 컴포넌트를 사용하면 CSS를 별도로 import할 필요가 없습니다.
+
+```tsx
+import { OasisButton } from 'oasis-chat-button/react'
+
+function App() {
+  return (
+    <>
+      {/* 다크 모드 */}
+      <OasisButton theme="dark" />
+
+      {/* 라이트 모드 */}
+      <OasisButton theme="light" />
+
+      {/* 자동 모드 (시스템 설정 따름, 기본값) */}
+      <OasisButton theme="auto" />
+    </>
+  )
+}
+```
+
+### Vue
+
+Vue 프로젝트에서 사용할 때도 wrapper 컴포넌트를 사용하면 CSS를 별도로 import할 필요가 없습니다.
+
+```vue
+<script setup>
+import { OasisButton } from 'oasis-chat-button/vue'
+</script>
+
+<template>
+  <!-- 다크 모드 -->
+  <OasisButton :theme="'dark'" />
+
+  <!-- 라이트 모드 -->
+  <OasisButton :theme="'light'" />
+
+  <!-- 자동 모드 (시스템 설정 따름, 기본값) -->
+  <OasisButton :theme="'auto'" />
+</template>
+```
+
+### Vanilla JS
+
+바닐라 JavaScript나 다른 프레임워크에서 사용할 때는 CSS를 수동으로 import해야 합니다.
+
+```js
+import { createButton } from 'oasis-chat-button'
+import 'oasis-chat-button/style.css' // CSS 파일 import 필요
+
+// 다크 모드
+const btnDark = createButton({
+  theme: 'dark',
+})
+
+// 라이트 모드
+const btnLight = createButton({
+  theme: 'light',
+})
+
+// 자동 모드 (시스템 설정 따름, 기본값)
+const btnAuto = createButton({
+  theme: 'auto', // 또는 생략 가능
+})
+
+document.body.appendChild(btnDark)
+```
+
+**참고**: React나 Vue wrapper를 사용할 때는 CSS를 별도로 import할 필요가 없습니다. wrapper 컴포넌트 내부에서 자동으로 CSS가 포함됩니다.
+
+## API
+
+### `createButton(options)`
+
+채팅 버튼을 생성하고 반환합니다.
+
+#### Parameters
+
+- `options.theme` (string, 선택): 테마 설정
+  - `'light'`: 라이트 모드
+  - `'dark'`: 다크 모드
+  - `'auto'`: 시스템 설정에 따라 자동 (기본값)
+
+#### Returns
+
+- `HTMLElement`: 생성된 버튼 컨테이너 요소
+
+#### Notes
+
+- 버튼은 싱글톤 패턴으로 관리되며, 여러 번 호출해도 하나의 인스턴스만 존재합니다.
+- 버튼 클릭 시 채팅 패널이 토글됩니다.
+- 로그인이 필요한 경우 패널 내에서 직접 로그인할 수 있습니다.
+- `theme`이 `'auto'`로 설정된 경우, 시스템의 다크모드 설정을 자동으로 감지하여 적용합니다.
+
+### React 컴포넌트: `OasisButton`
+
+#### Props
+
+```typescript
+interface OasisButtonProps {
+  theme?: 'light' | 'dark' | 'auto' // 기본값: 'auto'
+}
+```
+
+### Vue 컴포넌트: `OasisButton`
+
+#### Props
+
+```typescript
+{
+  theme?: 'light' | 'dark' | 'auto' // 기본값: 'auto'
+}
+```
+
+## 개발/빌드
+
+```bash
+npm run dev           # 데모 앱 실행 (Vite)
+npm run build:lib     # 라이브러리 빌드 (Vanilla JS, React, Vue 모두 빌드)
+```
+
+빌드 후 `dist/` 폴더에 다음 파일들이 생성됩니다:
+
+- `index.*.js` - Vanilla JS 버전
+- `react/index.*.js` - React wrapper 버전
+- `vue/index.*.js` - Vue wrapper 버전
+- `oasis-chat-button.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-button/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
+```