npm package: @moss-tools/voice-server
Description: Optimized server-side utilities for LiveKit-based Moss voice agents.
Author: Moss Team
Latest version: 1.0.0-beta.3

# @moss-tools/voice-server

Optimized server-side utilities for LiveKit-based Moss voice agents. Handles secure token generation and connection management.

## Features

- **Token generation** - Create participant tokens with optimized permissions
- **Clean class-based API** - Simple, intuitive interface
- **Type-safe** - Full TypeScript support with detailed JSDoc comments

## Requirements

- Node.js 18.0.0 or higher

## Install

```bash
npm install @moss-tools/voice-server
```

## Usage

```ts
import { MossVoiceServer } from "@moss-tools/voice-server";

// Create and initialize (call once at app startup)
const voiceServer = await MossVoiceServer.create({
  projectId: process.env.MOSS_PROJECT_ID!,
  projectKey: process.env.MOSS_PROJECT_KEY!,
  voiceAgentId: process.env.MOSS_VOICE_AGENT_ID!,
});

// Get voice agent server URL for clients
const serverUrl = voiceServer.getServerUrl();

// Create participant tokens
const token = await voiceServer.createParticipantToken(
  { identity: "user_123", name: "John Doe" },
  "support_room_456"
);
```

The MossVoiceServer class securely fetches and caches your voice agent credentials, then uses them to generate participant tokens.

## API

### `MossVoiceServer.create(config): Promise<MossVoiceServer>`

Create and initialize a MossVoiceServer instance by fetching credentials from Moss API.

**Parameters:**
- `config.projectId` - Your Moss project ID
- `config.projectKey` - Your Moss project key
- `config.voiceAgentId` - Voice agent ID to use

**Returns:** Initialized `MossVoiceServer` instance

**Example:**
```ts
const voiceServer = await MossVoiceServer.create({
  projectId: "your-project-id",
  projectKey: "your-project-key",
  voiceAgentId: "your-voice-agent-id",
});
```

### `voiceServer.getServerUrl(): string`

Get the voice agent server URL for client connections.

**Returns:** Voice agent server URL (e.g., `wss://your-agent.livekit.cloud`)

**Note:** Credentials are kept secure on the server and never exposed.

### `voiceServer.createParticipantToken(userInfo, roomName, agentName?): Promise<string>`

Create and sign a participant token for joining a voice session.

**Parameters:**
- `userInfo` - User identity and name
  - `identity` - Unique user identifier
  - `name` - Display name for the participant
- `roomName` - Room name to join
- `agentName` - (Optional) Override default voice agent name

**Returns:** Signed JWT token valid for 15 minutes

**Example:**
```ts
const token = await voiceServer.createParticipantToken(
  { identity: "user_123", name: "John Doe" },
  "support_room_456"
);
```

### `voiceServer.getAgentName(): string`

Get the configured voice agent name.

**Returns:** Voice agent name

## Environment Variables

Configure using environment variables:

```bash
MOSS_PROJECT_ID=your-project-id
MOSS_PROJECT_KEY=your-project-key
MOSS_VOICE_AGENT_ID=your-voice-agent-id
```

Then in your code:

```ts
const voiceServer = await MossVoiceServer.create({
  projectId: process.env.MOSS_PROJECT_ID!,
  projectKey: process.env.MOSS_PROJECT_KEY!,
  voiceAgentId: process.env.MOSS_VOICE_AGENT_ID!,
});
```

## Development

```bash
npm install
npm run build
npm test
```

Build output is emitted to `dist/`.