Skip to main content

​
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 GitHub Package Registry. Make sure you have authenticated with GitHub Packages. 
npm install @principles-first/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

config.js
import React from 'react';
import { AgentProvider, FloatingActionBar, MossSDKConfig, LogLevel } from '@principles-first/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:
​
apiUrl
string
required
The base HTTP URL of your backend agent service.
​
applicationName
string
required
A unique identifier for the client application integrating the SDK.
​
userId
string
required
A unique identifier for the end-user within your application.
​
apiKey
string
An optional API key for authenticating with the backend service.
​
observeTargetSelector
string
default:"'body'"
The CSS selector for the root element to observe for DOM changes.
​
logLevel
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.
​
debugMode
boolean
default:"false"
Enables or disables debug features in the SDK.
​
screenshotMode
enum
default:"'fullpage'"
Controls the screenshot capture mode when vision is enabled. Can be 'fullpage' or 'viewport'.
​
stability
StabilityConfig
Configuration for the DOM stability detection strategy. See StabilityConfig section below.
​
pageSanitizationScript
(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.
​
language
enum
Sets a fixed language for the SDK UI. Supported values are 'en' and 'ko'. If not provided, the language is auto-detected.

​
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

import { useAgent } from '@principles-first/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:
​
isConnected
boolean
Indicates if the SDK is successfully connected to the backend.
​
isChatOpen
boolean
Indicates if the main chat modal is currently open.
​
messages
ChatMessage[]
An array of chat messages in the current session.
​
sendMessage
(text: string) => Promise<void>
A function to send a message from the user to the assistant.
​
toggleChat
() => void
A function to open or close the chat modal.
​
startNewChat
() => Promise<void>
A function to clear the current session and start a new one.
​
isWaitingForResponse
boolean
Indicates if the SDK is currently waiting for a response from the backend.
​
useVision
boolean
Indicates if vision-based features are enabled for the current application.

​
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

​
id
string
A unique identifier for the message.
​
sender
'user' | 'assistant'
Indicates whether the message was sent by the user or the assistant.
​
text
string
The content of the message.
​
timestamp
number
The Unix timestamp when the message was created.

​
StabilityConfig

An object to configure the DOM stability detection.