Oasis Chat

createButton을 제공하는 가벼운 바닐라 JS 채팅 버튼 컴포넌트입니다. React와 Vue를 위한 wrapper 컴포넌트도 제공됩니다.

현재 버전: 0.4.0

주요 기능

• 💬 실시간 스트리밍 채팅: SSE(Server-Sent Events)를 통한 실시간 응답 스트리밍
• 🔐 자동 로그인: 계정 정보 제공 시 버튼 생성과 동시에 자동 로그인
• 🎨 반응형 UI: 모던하고 세련된 사용자 인터페이스
• 🔄 토글 패널: 버튼 클릭으로 채팅 패널 열기/닫기
• 📱 외부 클릭 감지: 패널 외부 클릭 시 자동으로 패널 닫기
• 📝 메시지 히스토리: 이전 대화 기록 관리
• 🚀 다중 프레임워크 지원: Vanilla JS, React, Vue 지원
• 📦 TypeScript 지원: 완전한 TypeScript 타입 정의 제공
• 🎯 경량화: 최소한의 의존성으로 가벼운 번들 사이즈

설치

npm install oasis-chat

의존성

이 라이브러리는 내부적으로 axios를 사용합니다. axios는 자동으로 설치됩니다.

Peer Dependencies

React 또는 Vue를 사용하는 경우, 해당 프레임워크가 프로젝트에 설치되어 있어야 합니다:

• React: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.1 || ^19.1.2 || ^19.2.1 || >=19.3.0 || >=20.0.0
• Vue: ^3.0.0

보안 참고사항: React 19.0.0, 19.1.0, 19.1.1, 19.2.0 버전은 CVE-2025-55182 취약점이 있어 사용하지 않습니다. 반드시 패치된 버전(19.0.1, 19.1.2, 19.2.1 이상)을 사용해주세요.

프록시 설정

이 라이브러리는 /oasis 경로로 API 요청을 보냅니다. CORS 문제를 해결하기 위해 프로젝트의 개발 서버나 프록시에서 /oasis 경로를 프록시하도록 설정해야 합니다.

개발 서버 프록시 설정

Vite

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

// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/oasis/:path*',
        destination: 'https://oasis-dev.haiqv.ai/api/:path*',
      },
    ]
  },
}

Create React App

// 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할 필요가 없습니다.

import { OasisButton } from 'oasis-chat/react'

function App() {
  return (
    <OasisButton
      account_id="your-account-id"
      password="your-password"
      assistant_uuid="your-assistant-uuid"
    />
  )
}

Vue

Vue 프로젝트에서 사용할 때도 wrapper 컴포넌트를 사용하면 CSS를 별도로 import할 필요가 없습니다.

<script setup>
import { OasisButton } from 'oasis-chat/vue'
</script>

<template>
  <OasisButton
    account_id="your-account-id"
    password="your-password"
    assistant_uuid="your-assistant-uuid"
  />
</template>

Vanilla JS

바닐라 JavaScript나 다른 프레임워크에서 사용할 때는 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)

참고: React나 Vue wrapper를 사용할 때는 CSS를 별도로 import할 필요가 없습니다. wrapper 컴포넌트 내부에서 자동으로 CSS가 포함됩니다.

API

createButton(options)

채팅 버튼을 생성하고 반환합니다.

Parameters

• options.account_id (string, 선택): 로그인에 사용할 계정 ID. 제공된 경우 버튼 생성 시 자동으로 로그인을 시도합니다.
• options.password (string, 선택): 로그인에 사용할 비밀번호. account_id와 함께 제공되어야 합니다.
• options.assistant_uuid (string, 필수): 채팅에 사용할 어시스턴트 UUID

Returns

• HTMLElement: 생성된 버튼 컨테이너 요소

Notes

• account_id와 password를 제공하지 않으면 버튼이 생성되지만 로그인은 수행되지 않습니다.
• 버튼은 싱글톤 패턴으로 관리되며, 여러 번 호출해도 하나의 인스턴스만 존재합니다.
• 버튼 클릭 시 채팅 패널이 토글됩니다.

React 컴포넌트: OasisButton

Props

interface OasisButtonProps {
  account_id: string
  password: string
  assistant_uuid: string
}

Vue 컴포넌트: OasisButton

Props

{
  account_id: string
  password: string
  assistant_uuid: string
}

개발/빌드

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.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해야 합니다:

import 'oasis-chat/style.css'

React나 Vue wrapper를 사용하는 경우 자동으로 CSS가 포함되므로 별도 import가 필요 없습니다.

로그인 실패

account_id와 password가 올바르게 제공되었는지 확인하세요. 네트워크 탭에서 API 요청이 제대로 전송되는지 확인할 수 있습니다.

스트리밍 응답이 작동하지 않음

브라우저가 Server-Sent Events (SSE)를 지원하는지 확인하세요. 최신 브라우저는 모두 SSE를 지원합니다.

React/Vue 컴포넌트가 렌더링되지 않음

필수 peer dependencies가 설치되어 있는지 확인하세요:

# React 사용 시
npm install react react-dom

# Vue 사용 시
npm install vue

기여하기

버그 리포트나 기능 제안은 GitHub Issues를 통해 제출해주세요.

라이선스

MIT