> ## 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 Reference

> Reference documentation for the Moss React SDK, including configuration, components, and hooks for integrating the AI assistant into your web application.

# React SDK Reference

The Moss React SDK provides a set of React components and hooks to integrate a powerful AI assistant into your web application. It handles state management, communication with the backend, and UI rendering, all encapsulated within a Shadow DOM to prevent style conflicts.

## Installation

Install the SDK package from the public NPM registry.

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

## `AgentProvider`

The `AgentProvider` is the core component of the SDK. It sets up the context, manages the connection to the backend, and should wrap the part of your application where you want the assistant to be available.

### Usage

```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', // Your backend API URL
  applicationName: 'your-app-name',
  userId: 'user-123',
  debugMode: true,
};

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

### Configuration (`MossSDKConfig`)

The `AgentProvider` accepts a `config` object with the following properties:

<ParamField body="apiUrl" type="string" required>
  The base HTTP URL of your backend agent service.
</ParamField>

<ParamField body="applicationName" type="string" required>
  A unique identifier for the client application integrating the SDK.
</ParamField>

<ParamField body="userId" type="string" required>
  A unique identifier for the end-user within your application.
</ParamField>

<ParamField body="apiKey" type="string">
  An optional API key for authenticating with the backend service.
</ParamField>

<ParamField body="observeTargetSelector" type="string" default="'body'">
  The CSS selector for the root element to observe for DOM changes.
</ParamField>

<ParamField body="logLevel" type="enum">
  Sets the minimum log level for the SDK's internal logger.
  Can be `LogLevel.DEBUG`, `LogLevel.INFO`, `LogLevel.WARN`, `LogLevel.ERROR`, or `LogLevel.SILENT`.
</ParamField>

<ParamField body="debugMode" type="boolean" default="false">
  Enables or disables debug features in the SDK.
</ParamField>

<ParamField body="screenshotMode" type="enum" default="'fullpage'">
  Controls the screenshot capture mode when vision is enabled. Can be `'fullpage'` or `'viewport'`.
</ParamField>

<ParamField body="stability" type="StabilityConfig">
  Configuration for the DOM stability detection strategy. See `StabilityConfig` section below.
</ParamField>

<ParamField body="pageSanitizationScript" type="(document: Document) => void">
  An optional function that runs to sanitize the DOM before context capture. Use this to remove or modify elements that might confuse the AI.
</ParamField>

<ParamField body="language" type="enum">
  Sets a fixed language for the SDK UI. Supported values are `'en'` and `'ko'`. If not provided, the language is auto-detected.
</ParamField>

## `useAgent` Hook

The `useAgent` hook provides access to the SDK's state and core functionalities. It must be used within a component that is a child of `AgentProvider`.

### Usage

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

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

  return (
    <button onClick={toggleChat}>
      {isChatOpen ? 'Close Chat' : 'Open Chat'}
    </button>
  );
};
```

### Return Value (`AgentState`)

The hook returns an `AgentState` object with the following properties:

<ResponseField name="isConnected" type="boolean">
  Indicates if the SDK is successfully connected to the backend.
</ResponseField>

<ResponseField name="isChatOpen" type="boolean">
  Indicates if the main chat modal is currently open.
</ResponseField>

<ResponseField name="messages" type="ChatMessage[]">
  An array of chat messages in the current session.
</ResponseField>

<ResponseField name="sendMessage" type="(text: string) => Promise<void>">
  A function to send a message from the user to the assistant.
</ResponseField>

<ResponseField name="toggleChat" type="() => void">
  A function to open or close the chat modal.
</ResponseField>

<ResponseField name="startNewChat" type="() => Promise<void>">
  A function to clear the current session and start a new one.
</ResponseField>

<ResponseField name="isWaitingForResponse" type="boolean">
  Indicates if the SDK is currently waiting for a response from the backend.
</ResponseField>

<ResponseField name="useVision" type="boolean">
  Indicates if vision-based features are enabled for the current application.
</ResponseField>

## Components

The SDK includes pre-built components for a quick setup.

### `FloatingActionBar`

A ready-to-use floating action button that contains the main assistant button. It is rendered automatically within the `AgentProvider`.

### `AssistantButton`

A standalone button component that can be used to toggle the chat interface. Use this if you want to place the entry point manually instead of using the `FloatingActionBar`.

## Type Definitions

### `ChatMessage`

<ResponseField name="id" type="string">
  A unique identifier for the message.
</ResponseField>

<ResponseField name="sender" type="'user' | 'assistant'">
  Indicates whether the message was sent by the user or the assistant.
</ResponseField>

<ResponseField name="text" type="string">
  The content of the message.
</ResponseField>

<ResponseField name="timestamp" type="number">
  The Unix timestamp when the message was created.
</ResponseField>

### `StabilityConfig`

An object to configure the DOM stability detection.

<Expandable title="Properties">
  <ResponseField name="strategy" type="'debounce' | 'fixed'" required>
    The strategy to use for determining when the DOM is stable.
  </ResponseField>

  <ResponseField name="debounceDelay" type="number">
    The delay in milliseconds for the `debounce` strategy.
  </ResponseField>

  <ResponseField name="maxWaitTime" type="number">
    The maximum time to wait for stability in milliseconds for the `debounce` strategy.
  </ResponseField>

  <ResponseField name="waitTime" type="number">
    The fixed time to wait in milliseconds for the `fixed` strategy.
  </ResponseField>
</Expandable>