Oasis Chat

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

설치

npm install oasis-chat-button

의존성

이 라이브러리는 내부적으로 axios를 사용합니다. 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

// 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-button/react'

function App() {
  return (
    <>
      {/* 다크 모드 */}
      <OasisButton theme="dark" assistantUuid="your-assistant-uuid" />

      {/* 라이트 모드 */}
      <OasisButton theme="light" assistantUuid="your-assistant-uuid" />

      {/* 자동 모드 (시스템 설정 따름, 기본값) */}
      <OasisButton theme="auto" assistantUuid="your-assistant-uuid" />
    </>
  )
}

Vue

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

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

<template>
  <!-- 다크 모드 -->
  <OasisButton :theme="'dark'" :assistant-uuid="'your-assistant-uuid'" />

  <!-- 라이트 모드 -->
  <OasisButton :theme="'light'" :assistant-uuid="'your-assistant-uuid'" />

  <!-- 자동 모드 (시스템 설정 따름, 기본값) -->
  <OasisButton :theme="'auto'" :assistant-uuid="'your-assistant-uuid'" />
</template>

Vanilla JS

바닐라 JavaScript나 다른 프레임워크에서 사용할 때는 CSS를 수동으로 import해야 합니다.

import { createButton } from 'oasis-chat-button'
import 'oasis-chat-button/style.css' // CSS 파일 import 필요

// 다크 모드
const btnDark = createButton({
  theme: 'dark',
  assistantUuid: 'your-assistant-uuid',
})

// 라이트 모드
const btnLight = createButton({
  theme: 'light',
  assistantUuid: 'your-assistant-uuid',
})

// 자동 모드 (시스템 설정 따름, 기본값)
const btnAuto = createButton({
  theme: 'auto', // 또는 생략 가능
  assistantUuid: 'your-assistant-uuid',
})

document.body.appendChild(btnDark)

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

API

createButton(options)

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

Parameters

• options.assistantUuid (string, 필수): 어시스턴트 UUID
• options.theme (string, 선택): 테마 설정
  • 'light': 라이트 모드
  • 'dark': 다크 모드
  • 'auto': 시스템 설정에 따라 자동 (기본값)

Returns

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

Notes

• 버튼은 싱글톤 패턴으로 관리되며, 여러 번 호출해도 하나의 인스턴스만 존재합니다.
• 버튼 클릭 시 채팅 패널이 토글됩니다.
• 로그인이 필요한 경우 패널 내에서 직접 로그인할 수 있습니다.
• theme이 'auto'로 설정된 경우, 시스템의 다크모드 설정을 자동으로 감지하여 적용합니다.
• assistantUuid는 필수 파라미터이며, 채팅 기능을 사용하기 위해 반드시 제공되어야 합니다.

React 컴포넌트: OasisButton

Props

interface OasisButtonProps {
  assistantUuid: string // 필수: 어시스턴트 UUID
  theme?: 'light' | 'dark' | 'auto' // 기본값: 'auto'
}

Vue 컴포넌트: OasisButton

Props

{
  assistantUuid: string // 필수: 어시스턴트 UUID
  theme?: 'light' | 'dark' | 'auto' // 기본값: 'auto'
}

개발/빌드

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

import 'oasis-chat-button/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