@broadreachalliance/q-assistant/README.md

A React-based voice assistant

# Q-Assistant

Q-Assistant is an NPM package that provides voice assistant capabilities for Contract Q web application. It includes a UI component for selecting and saving voice settings, as well as a custom hook for managing voice interactions.

## Installation

To install the package, run:

```sh
npm install @broadreachalliance/q-assistant
```

or with Yarn:

```sh
yarn add @broadreachalliance/q-assistant
```

## Usage

### Importing Components

```tsx
import { AssistantVoiceSettings, useAssistant } from "@broadreachalliance/q-assistant";
```

### Example Implementation

```tsx
function App() {
  const { startListening, stopListening, state } = useAssistant();

  const handleToggleListening = () => {
    if (state === "listening") {
      stopListening();
    } else {
      startListening();
    }
  };

  return (
    <div>
      <AssistantVoiceSettings />
      <button 
        onClick={handleToggleListening} 
        className="w-[20%] bg-[#1f4745] ml-auto text-white text-sm py-2 rounded-md shadow-md hover:bg-[#2ba49e]"
      >
        {state === "listening" ? "Stop Recording" : "Start Recording"}
      </button>
      <div>{state}</div>
    </div>
  );
}
```

## Environment Variables

The assistant API endpoint should be defined in the `.env` file:

```env
NEXT_PUBLIC_AI_ASSISTANT_HOST=<your-api-endpoint>
```

## Local Storage Requirements

- **User Data:** Must be stored in local storage under the key `currentUser` and should contain a `userID`.
- **Authorization Token:** The customer's authorization token must be available in local storage under the key `token`.

## API Reference

### `AssistantVoiceSettings`
A UI component that allows users to select and save a preferred voice to local storage. The saved voice is used for chatbot response playback.

### `useAssistant` Hook
A custom hook that provides functions and state for voice interaction.

#### State
- `idle` - No active voice interaction.
- `listening` - Actively capturing voice input.
- `responding` - Processing a response.
- `processing` - Handling voice data.

#### Functions
- `startListening()` - Begins capturing voice input.
- `stopListening()` - Stops capturing voice input.

## License
MIT