@moss-tools/voice-server 1.0.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to @moss-tools/voice-server will be documented in this file.
+
+## [1.0.0-beta.1] - 2026-02-11
+
+Initial beta release.
+
+### Added
+- `MossVoiceServer` class for managing voice agent connections
+- `MossVoiceServer.create()` - Fetch and initialize credentials from Moss API
+- `voiceServer.getServerUrl()` - Get voice agent server URL
+- `voiceServer.createParticipantToken()` - Generate participant tokens
+- `voiceServer.getAgentName()` - Get configured agent name
+- Automatic credential caching
+- Full TypeScript support with JSDoc
+
+[1.0.0-beta.1]: https://github.com/InferEdge-Inc/moss/releases/tag/voice-server-v1.0.0-beta.1

package/README.md

@@ -0,0 +1,130 @@
+# @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/`.

package/dist/MossVoiceServer.d.ts

@@ -0,0 +1,84 @@
+import { type AccessTokenOptions } from "livekit-server-sdk";
+type MossVoiceServerConfig = {
+    projectId: string;
+    projectKey: string;
+    voiceAgentId: string;
+};
+/**
+ * Voice server client for managing voice agent connections and tokens.
+ *
+ * @example
+ * ```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!,
+ * });
+ *
+ * const url = voiceServer.getServerUrl();
+ * const token = await voiceServer.createParticipantToken(
+ *   { identity: "user_123", name: "John" },
+ *   "room_name"
+ * );
+ * ```
+ */
+export declare class MossVoiceServer {
+    private config;
+    private credentials;
+    private constructor();
+    /**
+     * Create and initialize a MossVoiceServer instance.
+     *
+     * @param config - Configuration object
+     * @param config.projectId - Moss project ID
+     * @param config.projectKey - Moss project key
+     * @param config.voiceAgentId - Voice agent ID to use
+     * @returns Initialized MossVoiceServer instance
+     *
+     * @throws Error if credentials cannot be fetched
+     */
+    static create(config: MossVoiceServerConfig): Promise<MossVoiceServer>;
+    /**
+     * Initialize by fetching credentials from the Moss API.
+     * Called automatically by MossVoiceServer.create().
+     */
+    private initialize;
+    /**
+     * Get the voice agent server URL for client connections.
+     *
+     * @returns Voice agent server URL (e.g., "wss://your-agent.livekit.cloud")
+     * @throws Error if not initialized
+     */
+    getServerUrl(): string;
+    /**
+     * Create a participant token for joining a voice session.
+     *
+     * @param userInfo - LiveKit AccessTokenOptions (identity, name, metadata, etc.)
+     * @param roomName - Room name to join
+     * @param agentName - (Optional) Override default voice agent name
+     * @returns Signed JWT token valid for 15 minutes
+     *
+     * @throws Error if not initialized
+     *
+     * @remarks
+     * Token TTL is automatically set to 15 minutes. If userInfo.ttl is provided, it will be overridden.
+     * Commonly used userInfo fields: identity (required), name, metadata.
+     *
+     * @example
+     * ```ts
+     * const token = await voiceServer.createParticipantToken(
+     *   { identity: "user_123", name: "John Doe" },
+     *   "support_room_456"
+     * );
+     * ```
+     */
+    createParticipantToken(userInfo: AccessTokenOptions, roomName: string, agentName?: string): Promise<string>;
+    /**
+     * Get the voice agent name from credentials.
+     *
+     * @returns Voice agent name
+     * @throws Error if not initialized
+     */
+    getAgentName(): string;
+}
+export {};

package/dist/MossVoiceServer.js

@@ -0,0 +1,151 @@
+import { AccessToken, RoomConfiguration, } from "livekit-server-sdk";
+const VOICE_AGENT_API_URL = "https://service.usemoss.dev/api/voice-agent-deploy/get-voice-agent";
+/**
+ * Voice server client for managing voice agent connections and tokens.
+ *
+ * @example
+ * ```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!,
+ * });
+ *
+ * const url = voiceServer.getServerUrl();
+ * const token = await voiceServer.createParticipantToken(
+ *   { identity: "user_123", name: "John" },
+ *   "room_name"
+ * );
+ * ```
+ */
+export class MossVoiceServer {
+    config;
+    credentials = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Create and initialize a MossVoiceServer instance.
+     *
+     * @param config - Configuration object
+     * @param config.projectId - Moss project ID
+     * @param config.projectKey - Moss project key
+     * @param config.voiceAgentId - Voice agent ID to use
+     * @returns Initialized MossVoiceServer instance
+     *
+     * @throws Error if credentials cannot be fetched
+     */
+    static async create(config) {
+        const instance = new MossVoiceServer(config);
+        await instance.initialize();
+        return instance;
+    }
+    /**
+     * Initialize by fetching credentials from the Moss API.
+     * Called automatically by MossVoiceServer.create().
+     */
+    async initialize() {
+        const { projectId, projectKey, voiceAgentId } = this.config;
+        if (!projectId || !projectKey || !voiceAgentId) {
+            throw new Error("projectId, projectKey, and voiceAgentId are required");
+        }
+        try {
+            const url = `${VOICE_AGENT_API_URL}?voice_agent_id=${encodeURIComponent(voiceAgentId)}`;
+            // Add 10 second timeout to prevent indefinite hangs
+            const response = await fetch(url, {
+                method: "GET",
+                headers: {
+                    "X-Project-Id": projectId,
+                    "X-Project-Key": projectKey,
+                },
+                signal: AbortSignal.timeout(10000),
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "Unknown error");
+                throw new Error(`Failed to fetch credentials: ${response.status} ${errorText}`);
+            }
+            this.credentials = (await response.json());
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                // Provide clear error message for timeout
+                if (error.name === "TimeoutError" || error.name === "AbortError") {
+                    throw new Error("Failed to initialize MossVoiceServer: Request timed out after 10 seconds");
+                }
+                throw new Error(`Failed to initialize MossVoiceServer: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get the voice agent server URL for client connections.
+     *
+     * @returns Voice agent server URL (e.g., "wss://your-agent.livekit.cloud")
+     * @throws Error if not initialized
+     */
+    getServerUrl() {
+        if (!this.credentials) {
+            throw new Error("MossVoiceServer not initialized");
+        }
+        return this.credentials.voice_agent_url;
+    }
+    /**
+     * Create a participant token for joining a voice session.
+     *
+     * @param userInfo - LiveKit AccessTokenOptions (identity, name, metadata, etc.)
+     * @param roomName - Room name to join
+     * @param agentName - (Optional) Override default voice agent name
+     * @returns Signed JWT token valid for 15 minutes
+     *
+     * @throws Error if not initialized
+     *
+     * @remarks
+     * Token TTL is automatically set to 15 minutes. If userInfo.ttl is provided, it will be overridden.
+     * Commonly used userInfo fields: identity (required), name, metadata.
+     *
+     * @example
+     * ```ts
+     * const token = await voiceServer.createParticipantToken(
+     *   { identity: "user_123", name: "John Doe" },
+     *   "support_room_456"
+     * );
+     * ```
+     */
+    async createParticipantToken(userInfo, roomName, agentName) {
+        if (!this.credentials) {
+            throw new Error("MossVoiceServer not initialized");
+        }
+        const { voice_agent_api_key, voice_agent_api_secret, voice_agent_name } = this.credentials;
+        const at = new AccessToken(voice_agent_api_key, voice_agent_api_secret, {
+            ...userInfo,
+            ttl: "15m",
+        });
+        const grant = {
+            room: roomName,
+            roomJoin: true,
+            canPublish: true,
+            canPublishData: true,
+            canSubscribe: true,
+        };
+        at.addGrant(grant);
+        const effectiveAgentName = agentName ?? voice_agent_name;
+        if (effectiveAgentName) {
+            at.roomConfig = new RoomConfiguration({
+                agents: [{ agentName: effectiveAgentName }],
+            });
+        }
+        return at.toJwt();
+    }
+    /**
+     * Get the voice agent name from credentials.
+     *
+     * @returns Voice agent name
+     * @throws Error if not initialized
+     */
+    getAgentName() {
+        if (!this.credentials) {
+            throw new Error("MossVoiceServer not initialized");
+        }
+        return this.credentials.voice_agent_name;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { MossVoiceServer } from "./MossVoiceServer.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { MossVoiceServer } from "./MossVoiceServer.js";

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@moss-tools/voice-server",
+  "version": "1.0.0-beta.1",
+  "description": "Optimized server-side utilities for LiveKit-based Moss voice agents.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && tsx --test test/voice-server.test.ts"
+  },
+  "keywords": [
+    "moss",
+    "voice",
+    "agent",
+    "livekit",
+    "realtime",
+    "token",
+    "server"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/InferEdge-Inc/moss.git",
+    "directory": "javascript/voice-server"
+  },
+  "author": "Moss Team",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "livekit-server-sdk": "^2.15.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}