# Rqmii React Agent SDK (Simple Guide)

Minimal guide to integrate quickly.

## Install

```bash
npm install @rqmii_immersive/agent-react-sdk
```

## Required Config

You need:

- `restUrl` -> REST API URL
- `wsUrl` -> realtime Socket.IO URL

Example env:

```env
VITE_AGENT_API_URL=https://api.example.com
VITE_AGENT_WS_URL=wss://realtime.example.com
```

## Basic Usage

```jsx
import {
  RqmiiAgentRoom,
  useRqmiiConnection,
  useRqmiiMessages,
  useRqmiiPressToTalk,
} from "@rqmii_immersive/agent-react-sdk";

function ChatUI() {
  const { connectionState, isSessionReady, error } = useRqmiiConnection();
  const { messages, sendTextMessage } = useRqmiiMessages();
  const { eventHandlers, isRecording } = useRqmiiPressToTalk();

  return (
    <div>
      <div>{connectionState}</div>
      <div>ready: {String(isSessionReady)}</div>
      {error && <div style={{ color: "red" }}>{error}</div>}

      <button onClick={() => sendTextMessage("Hello")}>Send</button>
      <button {...eventHandlers}>
        {isRecording ? "Recording..." : "Hold to Talk"}
      </button>
      <pre>{JSON.stringify(messages, null, 2)}</pre>
    </div>
  );
}

export default function App() {
  return (
    <RqmiiAgentRoom
      wsUrl={import.meta.env.VITE_AGENT_WS_URL}
      restUrl={import.meta.env.VITE_AGENT_API_URL}
      session={{ mode: "initialize", apiKey: "YOUR_API_KEY", language: "en" }}
      connect
    >
      <ChatUI />
    </RqmiiAgentRoom>
  );
}
```

## Cloud Avatar

```jsx
import {
  RqmiiCloudAvatarPlayer,
  useRqmiiAvatar,
} from "@rqmii_immersive/agent-react-sdk";

function CloudAvatarUI() {
  const { isAvatarSpeaking, cloudStreamState } = useRqmiiAvatar();

  return (
    <>
      <div>speaking: {String(isAvatarSpeaking)}</div>
      <div>stream: {cloudStreamState}</div>
      <RqmiiCloudAvatarPlayer muted={false} />
    </>
  );
}
```

## Desktop Avatar Join

```jsx
<RqmiiAgentRoom
  wsUrl={WS_URL}
  restUrl={REST_URL}
  session={{ mode: "join_desktop", uniqueId: "A1B2C3" }}
  connect
>
  <YourUI />
</RqmiiAgentRoom>
```

## Voice Input / Output

- send mic chunks: `sendAudioChunk(chunk)`
- end utterance: `endAudioStream()`
- interrupt: `interrupt()`
- SDK plays output audio internally using `pcm-stream-player`

## Notes

- Reconnection is built-in and follows backend reconnect credential flow.
- Avatar speaking state comes from backend avatar events.
- For full docs, see `README.md`.
