> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viamoss.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# React SDK 레퍼런스

> AI 어시스턴트를 웹 애플리케이션에 통합하기 위한 Moss React SDK의 레퍼런스 문서입니다. 설정, 컴포넌트, 훅을 포함합니다.

# React SDK 레퍼런스

Moss React SDK는 강력한 AI 어시스턴트를 웹 애플리케이션에 통합하기 위한 React 컴포넌트와 훅 세트를 제공합니다. 상태 관리, 백엔드와의 통신, UI 렌더링을 모두 처리하며, 스타일 충돌을 방지하기 위해 Shadow DOM 내에 캡슐화되어 있습니다.

## 설치

공개 NPM 레지스트리에서 SDK 패키지를 설치합니다.

```bash theme={null}
npm install @viamoss/moss-sdk
```

## `AgentProvider`

`AgentProvider`는 SDK의 핵심 컴포넌트입니다. 컨텍스트를 설정하고 백엔드와의 연결을 관리하며, 어시스턴트를 사용하려는 애플리케이션 부분을 감싸야 합니다.

### 사용법

```tsx config.js theme={null}
import React from 'react';
import { AgentProvider, FloatingActionBar, MossSDKConfig, LogLevel } from '@viamoss/moss-sdk';

const config: MossSDKConfig = {
  apiUrl: 'http://localhost:8000', // 백엔드 API URL
  applicationName: 'your-app-name',
  userId: 'user-123',
  debugMode: true,
};

function App() {
  return (
    <AgentProvider config={config}>
      <YourAppContent />
      <FloatingActionBar />
    </AgentProvider>
  );
}
```

### 설정 (`MossSDKConfig`)

`AgentProvider`는 다음 속성을 가진 `config` 객체를 받습니다:

<ParamField body="apiUrl" type="string" required>
  백엔드 에이전트 서비스의 기본 HTTP URL입니다.
</ParamField>

<ParamField body="applicationName" type="string" required>
  SDK를 통합하는 클라이언트 애플리케이션의 고유 식별자입니다.
</ParamField>

<ParamField body="userId" type="string" required>
  애플리케이션 내 최종 사용자의 고유 식별자입니다.
</ParamField>

<ParamField body="apiKey" type="string">
  백엔드 서비스 인증을 위한 선택적 API 키입니다.
</ParamField>

<ParamField body="observeTargetSelector" type="string" default="'body'">
  DOM 변경을 관찰할 루트 요소의 CSS 선택자입니다.
</ParamField>

<ParamField body="logLevel" type="enum">
  SDK 내부 로거의 최소 로그 레벨을 설정합니다.
  `LogLevel.DEBUG`, `LogLevel.INFO`, `LogLevel.WARN`, `LogLevel.ERROR`, 또는 `LogLevel.SILENT`가 될 수 있습니다.
</ParamField>

<ParamField body="debugMode" type="boolean" default="false">
  SDK에서 디버그 기능을 활성화하거나 비활성화합니다.
</ParamField>

<ParamField body="screenshotMode" type="enum" default="'fullpage'">
  비전 기능이 활성화되었을 때 스크린샷 캡처 모드를 제어합니다. `'fullpage'` 또는 `'viewport'`가 될 수 있습니다.
</ParamField>

<ParamField body="stability" type="StabilityConfig">
  DOM 안정성 감지 전략에 대한 설정입니다. 아래의 `StabilityConfig` 섹션을 참조하세요.
</ParamField>

<ParamField body="pageSanitizationScript" type="(document: Document) => void">
  컨텍스트 캡처 전에 DOM을 정리하기 위해 실행되는 선택적 함수입니다. AI를 혼란스럽게 할 수 있는 요소를 제거하거나 수정하는 데 사용합니다.
</ParamField>

<ParamField body="language" type="enum">
  SDK UI의 고정 언어를 설정합니다. 지원되는 값은 `'en'`과 `'ko'`입니다. 제공되지 않으면 언어가 자동으로 감지됩니다.
</ParamField>

## `useAgent` 훅

`useAgent` 훅은 SDK의 상태 및 핵심 기능에 대한 접근을 제공합니다. `AgentProvider`의 자식인 컴포넌트 내에서 사용해야 합니다.

### 사용법

```tsx theme={null}
import { useAgent } from '@viamoss/moss-sdk';

const MyComponent = () => {
  const { isChatOpen, toggleChat, sendMessage } = useAgent();

  return (
    <button onClick={toggleChat}>
      {isChatOpen ? '채팅 닫기' : '채팅 열기'}
    </button>
  );
};
```

### 반환 값 (`AgentState`)

이 훅은 다음 속성을 가진 `AgentState` 객체를 반환합니다:

<ResponseField name="isConnected" type="boolean">
  SDK가 백엔드에 성공적으로 연결되었는지 여부를 나타냅니다.
</ResponseField>

<ResponseField name="isChatOpen" type="boolean">
  메인 채팅 모달이 현재 열려 있는지 여부를 나타냅니다.
</ResponseField>

<ResponseField name="messages" type="ChatMessage[]">
  현재 세션의 채팅 메시지 배열입니다.
</ResponseField>

<ResponseField name="sendMessage" type="(text: string) => Promise<void>">
  사용자로부터 어시스턴트에게 메시지를 보내는 함수입니다.
</ResponseField>

<ResponseField name="toggleChat" type="() => void">
  채팅 모달을 열거나 닫는 함수입니다.
</ResponseField>

<ResponseField name="startNewChat" type="() => Promise<void>">
  현재 세션을 지우고 새 세션을 시작하는 함수입니다.
</ResponseField>

<ResponseField name="isWaitingForResponse" type="boolean">
  SDK가 현재 백엔드로부터 응답을 기다리고 있는지 여부를 나타냅니다.
</ResponseField>

<ResponseField name="useVision" type="boolean">
  현재 애플리케이션에 비전 기반 기능이 활성화되어 있는지 여부를 나타냅니다.
</ResponseField>

## 컴포넌트

SDK에는 빠른 설정을 위한 사전 빌드된 컴포넌트가 포함되어 있습니다.

### `FloatingActionBar`

메인 어시스턴트 버튼을 포함하는 즉시 사용 가능한 플로팅 액션 버튼입니다. `AgentProvider` 내에서 자동으로 렌더링됩니다.

### `AssistantButton`

채팅 인터페이스를 토글하는 데 사용할 수 있는 독립 실행형 버튼 컴포넌트입니다. `FloatingActionBar` 대신 수동으로 진입점을 배치하려는 경우 사용합니다.

## 타입 정의

### `ChatMessage`

<ResponseField name="id" type="string">
  메시지의 고유 식별자입니다.
</ResponseField>

<ResponseField name="sender" type="'user' | 'assistant'">
  메시지가 사용자에 의해 전송되었는지 또는 어시스턴트에 의해 전송되었는지를 나타냅니다.
</ResponseField>

<ResponseField name="text" type="string">
  메시지의 내용입니다.
</ResponseField>

<ResponseField name="timestamp" type="number">
  메시지가 생성된 Unix 타임스탬프입니다.
</ResponseField>

### `StabilityConfig`

DOM 안정성 감지를 구성하는 객체입니다.

<Expandable title="속성">
  <ResponseField name="strategy" type="'debounce' | 'fixed'" required>
    DOM이 안정적인지 판단하는 데 사용할 전략입니다.
  </ResponseField>

  <ResponseField name="debounceDelay" type="number">
    `debounce` 전략의 지연 시간(밀리초)입니다.
  </ResponseField>

  <ResponseField name="maxWaitTime" type="number">
    `debounce` 전략에서 안정성을 기다리는 최대 시간(밀리초)입니다.
  </ResponseField>

  <ResponseField name="waitTime" type="number">
    `fixed` 전략에서 기다릴 고정 시간(밀리초)입니다.
  </ResponseField>
</Expandable>