# Hiyve SDK

> Hiyve SDK is a complete suite for building real-time video conferencing applications with WebRTC, recording, transcription, and AI-powered features. It provides drop-in React/Angular/React Native components or a framework-agnostic core library.

## Authentication Model

Hiyve has two credential types:

- **API Key** (`pk_live_*` / `pk_test_*`) — identifies your app. Required for all Hiyve apps.
- **Client Secret** (`sk_live_*` / `sk_test_*`) — generates room tokens for WebRTC connections. Server-side only.

Three auth paths depending on your use case:

| Use case | Credentials needed | Packages | Server required? |
|----------|-------------------|----------|-----------------|
| **Identity only** (login, register, profile) | API key (`pk_*`) | `@hiyve/identity-client`, `@hiyve/react-identity` | No — client-side only |
| **Video conferencing** (rooms, WebRTC) | API key (`pk_*`) + client secret (`sk_*`) | `@hiyve/admin`, `@hiyve/rtc-client`, `@hiyve/react` | Yes — generates room tokens |
| **Cloud/AI features** (summaries, intelligence) | API key (`pk_*`) on server | `@hiyve/cloud`, `@hiyve/react-intelligence` | Yes — generates cloud tokens |

## Getting Started

1. Get your API key (`pk_*`) and client secret (`sk_*`) from https://console.hiyve.dev
2. Run: `npx @hiyve/cli login` (uses your `pk_*` API key)
3. Install packages: `npm install @hiyve/rtc-client @hiyve/react @hiyve/react-ui`
4. Server setup: `npm install @hiyve/admin`

Minimal React app:

```jsx
import { HiyveProvider } from '@hiyve/react';
import { VideoGrid, ControlBar } from '@hiyve/react-ui';

function App() {
  return (
    <HiyveProvider>
      <VideoRoom />
    </HiyveProvider>
  );
}

function VideoRoom() {
  const { createRoom, joinRoom, leaveRoom } = useConnection();
  const { isInRoom } = useRoom();

  if (!isInRoom) {
    return <button onClick={() => createRoom('my-room', 'user-123')}>Create Room</button>;
  }
  return (
    <div style={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
      <VideoGrid />
      <ControlBar onLeave={leaveRoom} />
    </div>
  );
}
```

Server (Express):

```js
import express from 'express';
import { mountHiyveRoutes, loadHiyveConfig } from '@hiyve/admin';

const app = express();
app.use(express.json());
mountHiyveRoutes(app, loadHiyveConfig());
app.listen(3000);
```

Set `APIKEY` (`pk_*`) and `CLIENT_SECRET` (`sk_*`, required for video conferencing) environment variables from console.hiyve.dev. Identity-only apps need only the API key.

## Architecture

```
@hiyve/rtc-client          (JS — WebRTC client, framework-agnostic)
       │
       ▼
@hiyve/core                (TS — HiyveStore: state store + event handlers + actions)
   │        │
   ▼        ▼
@hiyve/react  @hiyve/angular   (framework bindings — hooks/services)
   │
   ▼
React component packages   (React + MUI, consume @hiyve/react hooks)

@hiyve/cloud               (TS — AI cloud services, framework-agnostic)
@hiyve/admin               (Node.js — server middleware + admin client)
@hiyve/identity-client      (JS — browser auth SDK, zero dependencies)
```

## Packages

### Foundation (framework-agnostic)
- @hiyve/rtc-client — WebRTC client for audio/video conferencing, recording, streaming, screen sharing
- @hiyve/core — State store (HiyveStore) with subscribe/getSlice API, 14 state slices, 40+ actions
- @hiyve/utilities — Shared helpers: getInitials, getUserColor, createDebugLogger, ErrorBoundary, withRetry, throttle
- @hiyve/cloud — AI cloud client: intelligence queries, live context, alerts, scheduling, usage tracking

### React (Web)
- @hiyve/react — Provider + 27 hooks (useConnection, useRoom, useParticipants, useLocalMedia, useChat, useRecording, useStreaming, useTranscription, etc.)
- @hiyve/react-ui — Video grid, video tile, control bar, device selector, participant list, sidebar, waiting room, join token
- @hiyve/react-room — Pre-built room: complete video conferencing in 5 lines of code
- @hiyve/react-rooms — Stored room management: list, create, edit, delete persistent rooms
- @hiyve/react-capture — Recording, streaming, and transcription components
- @hiyve/react-collaboration — Chat, polls, Q&A, and file manager
- @hiyve/react-intelligence — AI assistant, meeting summary, sentiment dashboard, alerts, scheduling
- @hiyve/react-notes — Rich text collaborative meeting notes
- @hiyve/react-reactions — Visual reactions and effects overlay — floating emojis, confetti, fireworks synced across participants
- @hiyve/react-whiteboard — Real-time collaborative whiteboard
- @hiyve/react-clips — Clip composition for highlight reels
- @hiyve/react-assignments — Assignment editor with activity tracking
- @hiyve/react-media-player — Audio/video player with waveform visualization

### Angular
- @hiyve/angular — Provider service, video grid, video tile, control bar (Angular 17–20)

### React Native
- @hiyve/rtc-client-rn — React Native WebRTC client for iOS and Android
- @hiyve/rn-core — State store for React Native (HiyveStoreRN)
- @hiyve/rn-react — Provider, 13 hooks, 5 components (VideoTile, VideoGrid, ControlBar, ParticipantList, WaitingRoom)
- @hiyve/rn-collaboration — Chat, polls, Q&A
- @hiyve/rn-capture — Recording, streaming, transcription
- @hiyve/rn-meeting — Alerts, meeting summary, join token

### Server & Auth
- @hiyve/admin — Express middleware (room tokens, cloud tokens, join tokens, identity proxy, health check) + AdminClient for profile/org management + auth middleware
- @hiyve/identity-client — Browser auth SDK: login, register, JWT tokens, password reset, TFA, OAuth
- @hiyve/react-identity — React components/hooks for authentication flows
- @hiyve/cli — CLI: login, logout, whoami, list, init

## Documentation

Each package has a README with installation, quick start, props tables, and code examples. Fetch the raw markdown for the most useful content:

- Core: https://sdk.hiyve.dev/hiyve-components/latest/readmes/core.md
- React hooks: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react.md
- React UI: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-ui.md
- React Room: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-room.md
- React Capture: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-capture.md
- React Collaboration: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-collaboration.md
- React Intelligence: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-intelligence.md
- React Notes: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-notes.md
- React Reactions: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-reactions.md
- React Whiteboard: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-whiteboard.md
- React Rooms: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-rooms.md
- React Assignments: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-assignments.md
- React Clips: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-clips.md
- React Media Player: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-media-player.md
- Angular: https://sdk.hiyve.dev/hiyve-components/latest/readmes/angular.md
- Admin: https://sdk.hiyve.dev/hiyve-components/latest/readmes/admin.md
- Cloud: https://sdk.hiyve.dev/hiyve-components/latest/readmes/cloud.md
- Identity Client: https://sdk.hiyve.dev/hiyve-components/latest/readmes/identity-client.md
- React Identity: https://sdk.hiyve.dev/hiyve-components/latest/readmes/react-identity.md
- CLI: https://sdk.hiyve.dev/hiyve-components/latest/readmes/cli.md
- Utilities: https://sdk.hiyve.dev/hiyve-components/latest/readmes/utilities.md
- RTC Client: https://sdk.hiyve.dev/hiyve-components/latest/readmes/rtc-client.md
- RN Core: https://sdk.hiyve.dev/hiyve-components/latest/readmes/rn-core.md
- RN React: https://sdk.hiyve.dev/hiyve-components/latest/readmes/rn-react.md
- RN Collaboration: https://sdk.hiyve.dev/hiyve-components/latest/readmes/rn-collaboration.md
- RN Capture: https://sdk.hiyve.dev/hiyve-components/latest/readmes/rn-capture.md
- RN Meeting: https://sdk.hiyve.dev/hiyve-components/latest/readmes/rn-meeting.md

## Developer Guides

Step-by-step guides for common integration scenarios:

- Getting Started: https://sdk.hiyve.dev/guides/getting-started.md
- Server Integration: https://sdk.hiyve.dev/guides/server-integration.md
- Error Handling: https://sdk.hiyve.dev/guides/error-handling.md
- Browser Compatibility: https://sdk.hiyve.dev/guides/browser-compatibility.md
- Production Checklist: https://sdk.hiyve.dev/guides/production-checklist.md

TypeDoc API reference (full type signatures, all exports):
- All modules index: https://sdk.hiyve.dev/hiyve-components/latest/
- Per-module: https://sdk.hiyve.dev/hiyve-components/latest/modules/_hiyve_{package-name}.html
  (e.g., _hiyve_core.html, _hiyve_react.html, _hiyve_react_ui.html — use underscores for hyphens in package names with sub-names)
- RTC Client (JSDoc): https://sdk.hiyve.dev/hiyve-rtc-client/latest/

Package metadata (JSON): https://sdk.hiyve.dev/portal.config.json

## Key Hooks (@hiyve/react)

| Hook | Purpose |
|------|---------|
| useConnection() | createRoom, joinRoom, leaveRoom, isConnected |
| useRoom() | roomName, isInRoom, isOwner, roomInfo |
| useParticipants() | participants array, count |
| useParticipant(userId) | single participant data |
| useLocalMedia() | toggleAudio, toggleVideo, shareScreen, localStream |
| useDevices() | enumerate and select audio/video devices |
| useRecording() | startRecording, stopRecording, isRecording, duration |
| useStreaming() | startStreaming, stopStreaming, isStreaming |
| useTranscription() | transcription entries, toggle |
| useChat() | sendMessage, messages, unreadCount |
| useWaitingRoom() | pendingUsers, admitUser, denyUser |
| useHandRaise() | raiseHand, lowerHand, raisedHands |
| useIntelligenceStream() | coaching hints, topics, talk ratio |
| useAiChat() | AI conversation interface |
| useRoomFlow() | lobby/connecting/in-room state machine |
| useJoinToken() | token validation with auto-join |
| useClient() | raw RTC client access |

## Example Apps

- https://github.com/hiyve/hiyve-examples (full-example, token-room, AI room)

## Requirements

- Node.js >= 18
- React 18+ (for React packages)
- MUI v5 or v6 + Emotion (for @hiyve/react-ui)
- Angular 17–20 (for @hiyve/angular)
- All React component packages must be wrapped in `<HiyveProvider>`
- Server needs `APIKEY` (`pk_*`) env var from console.hiyve.dev; `CLIENT_SECRET` (`sk_*`) also required for video conferencing apps