@azure/ai-voicelive 1.0.0-alpha.20251117.2

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,358 @@
+# Azure VoiceLive client library for JavaScript
+
+Azure VoiceLive is a managed service that enables low-latency, high-quality speech-to-speech interactions for voice agents. The service consolidates speech recognition, generative AI, and text-to-speech functionalities into a single, unified interface, providing an end-to-end solution for creating seamless voice-driven experiences.
+
+Use the client library to:
+
+- Create real-time voice assistants and conversational agents
+- Build speech-to-speech applications with minimal latency
+- Integrate advanced conversational features like noise suppression and echo cancellation
+- Leverage multiple AI models (GPT-4o, GPT-4o-mini, Phi) for different use cases
+- Implement function calling and tool integration for dynamic responses
+- Create avatar-enabled voice interactions with visual components
+
+> Note: This package supports both browser and Node.js environments. WebSocket connections are used for real-time communication.
+
+## Getting started
+
+### Currently supported environments
+
+- [LTS versions of Node.js](https://github.com/nodejs/release#release-schedule)
+- Latest versions of Safari, Chrome, Edge and Firefox
+
+### Prerequisites
+
+- An [Azure subscription](https://azure.microsoft.com/free/)
+- An [Azure AI Foundry resource](https://learn.microsoft.com/azure/ai-services/openai/how-to/create-resource) with Voice Live API access
+
+### Install the package
+
+Install the Azure VoiceLive client library using npm:
+
+```bash
+npm install @azure/ai-voicelive
+```
+
+### Install the identity library
+
+VoiceLive clients authenticate using the Azure Identity Library. Install it as well:
+
+```bash
+npm install @azure/identity
+```
+
+### Configure TypeScript
+
+TypeScript users need to have Node type definitions installed:
+
+```bash
+npm install @types/node
+```
+
+You also need to enable `compilerOptions.allowSyntheticDefaultImports` in your tsconfig.json. Note that if you have enabled `compilerOptions.esModuleInterop`, `allowSyntheticDefaultImports` is enabled by default.
+
+### JavaScript Bundle
+
+To use this client library in the browser, first you need to use a bundler. For details on how to do this, please refer to our [bundling documentation](https://aka.ms/AzureSDKBundling).
+
+## Key concepts
+
+### VoiceLiveClient
+
+The primary interface for establishing connections to the Azure VoiceLive service. Use this client to authenticate and create sessions for real-time voice interactions.
+
+### VoiceLiveSession
+
+Represents an active WebSocket connection for real-time voice communication. This class handles bidirectional communication, allowing you to send audio input and receive audio output, text transcriptions, and other events in real-time.
+
+### Session Configuration
+
+The service uses session configuration to control various aspects of voice interaction:
+
+- **Turn Detection**: Configure how the service detects when users start and stop speaking
+- **Audio Processing**: Enable noise suppression and echo cancellation  
+- **Voice Selection**: Choose from standard Azure voices, high-definition voices, or custom voices
+- **Model Selection**: Select the AI model (GPT-4o, GPT-4o-mini, Phi variants) that best fits your needs
+
+### Models and Capabilities
+
+The VoiceLive API supports multiple AI models with different capabilities:
+
+| Model | Description | Use Case |
+|-------|-------------|----------|
+| `gpt-4o-realtime-preview` | GPT-4o with real-time audio processing | High-quality conversational AI |
+| `gpt-4o-mini-realtime-preview` | Lightweight GPT-4o variant | Fast, efficient interactions |
+| `phi4-mm-realtime` | Phi model with multimodal support | Cost-effective voice applications |
+
+### Conversational Enhancements
+
+The VoiceLive API provides Azure-specific enhancements:
+
+- **Azure Semantic VAD**: Advanced voice activity detection that removes filler words
+- **Noise Suppression**: Reduces environmental background noise
+- **Echo Cancellation**: Removes echo from the model's own voice
+- **End-of-Turn Detection**: Allows natural pauses without premature interruption
+
+## Authenticating with Azure Active Directory
+
+The VoiceLive service relies on Azure Active Directory to authenticate requests to its APIs. The [`@azure/identity`](https://www.npmjs.com/package/@azure/identity) package provides a variety of credential types that your application can use to do this. The [README for `@azure/identity`](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md) provides more details and samples to get you started.
+
+To interact with the Azure VoiceLive service, you need to create an instance of the `VoiceLiveClient` class, a **service endpoint** and a credential object. The examples shown in this document use a credential object named [`DefaultAzureCredential`][defaultazurecredential], which is appropriate for most scenarios, including local development and production environments. We recommend using a [managed identity][managed_identity] for authentication in production environments.
+
+You can find more information on different ways of authenticating and their corresponding credential types in the [Azure Identity documentation][azure_identity].
+
+Here's a quick example. First, import `DefaultAzureCredential` and `VoiceLiveClient`:
+
+```ts snippet:ReadmeSampleCreateClient
+import { DefaultAzureCredential } from "@azure/identity";
+import { VoiceLiveClient } from "@azure/ai-voicelive";
+
+const credential = new DefaultAzureCredential();
+
+// Build the URL to reach your AI Foundry resource
+const endpoint = "https://your-resource.cognitiveservices.azure.com";
+
+// Create the VoiceLive client
+const client = new VoiceLiveClient(endpoint, credential);
+```
+
+### Authentication with API Key
+
+For development scenarios, you can also authenticate using an API key:
+
+```ts snippet:ReadmeSampleCreateClientWithApiKey
+import { AzureKeyCredential } from "@azure/core-auth";
+import { VoiceLiveClient } from "@azure/ai-voicelive";
+
+const endpoint = "https://your-resource.cognitiveservices.azure.com";
+const credential = new AzureKeyCredential("your-api-key");
+
+const client = new VoiceLiveClient(endpoint, credential);
+```
+
+## Examples
+
+The following sections provide code snippets that cover some of the common tasks using Azure VoiceLive. The scenarios covered here consist of:
+
+- [Creating a basic voice assistant](#creating-a-basic-voice-assistant)
+- [Configuring session options](#configuring-session-options)
+- [Handling real-time events](#handling-real-time-events)
+- [Implementing function calling](#implementing-function-calling)
+
+### Creating a basic voice assistant
+
+This example shows how to create a simple voice assistant that can handle speech-to-speech interactions:
+
+```ts snippet:ReadmeSampleBasicVoiceAssistant
+import { DefaultAzureCredential } from "@azure/identity";
+import { VoiceLiveClient } from "@azure/ai-voicelive";
+
+const credential = new DefaultAzureCredential();
+const endpoint = "https://your-resource.cognitiveservices.azure.com";
+
+// Create the client
+const client = new VoiceLiveClient(endpoint, credential);
+
+// Create and connect a session
+const session = await client.startSession("gpt-4o-mini-realtime-preview");
+
+// Configure session for voice conversation
+await session.updateSession({
+  modalities: ["text", "audio"],
+  instructions: "You are a helpful AI assistant. Respond naturally and conversationally.",
+  voice: {
+    type: "azure-standard",
+    name: "en-US-AvaNeural",
+  },
+  turnDetection: {
+    type: "server_vad",
+    threshold: 0.5,
+    prefixPaddingMs: 300,
+    silenceDurationMs: 500,
+  },
+  inputAudioFormat: "pcm16",
+  outputAudioFormat: "pcm16",
+});
+```
+
+### Configuring session options
+
+You can customize various aspects of the voice interaction:
+
+```ts snippet:ReadmeSampleAdvancedConfiguration
+import { DefaultAzureCredential } from "@azure/identity";
+import { VoiceLiveClient } from "@azure/ai-voicelive";
+
+const credential = new DefaultAzureCredential();
+const endpoint = "https://your-resource.cognitiveservices.azure.com";
+const client = new VoiceLiveClient(endpoint, credential);
+const session = await client.startSession("gpt-4o-realtime-preview");
+
+// Advanced session configuration
+await session.updateSession({
+  modalities: ["audio", "text"],
+  instructions: "You are a customer service representative. Be helpful and professional.",
+  voice: {
+    type: "azure-custom",
+    name: "your-custom-voice-name",
+    endpointId: "your-custom-voice-endpoint",
+  },
+  turnDetection: {
+    type: "server_vad",
+    threshold: 0.6,
+    prefixPaddingMs: 200,
+    silenceDurationMs: 300,
+  },
+  inputAudioFormat: "pcm16",
+  outputAudioFormat: "pcm16",
+});
+```
+
+### Handling real-time events
+
+The VoiceLive client provides event-driven communication for real-time interactions:
+
+```ts snippet:ReadmeSampleEventHandling
+import { DefaultAzureCredential } from "@azure/identity";
+import { VoiceLiveClient } from "@azure/ai-voicelive";
+
+const credential = new DefaultAzureCredential();
+const endpoint = "https://your-resource.cognitiveservices.azure.com";
+const client = new VoiceLiveClient(endpoint, credential);
+const session = await client.startSession("gpt-4o-mini-realtime-preview");
+
+// Set up event handlers using subscription pattern
+const subscription = session.subscribe({
+  onResponseAudioDelta: async (event, context) => {
+    // Handle incoming audio chunks
+    const audioData = event.delta;
+    // Play audio using Web Audio API or other audio system
+    playAudioChunk(audioData);
+  },
+
+  onResponseTextDelta: async (event, context) => {
+    // Handle incoming text deltas
+    console.log("Assistant:", event.delta);
+  },
+
+  onInputAudioTranscriptionCompleted: async (event, context) => {
+    // Handle user speech transcription
+    console.log("User said:", event.transcript);
+  },
+});
+
+// Send audio data from microphone
+function sendAudioChunk(audioBuffer: ArrayBuffer) {
+  session.sendAudio(audioBuffer);
+}
+```
+
+### Implementing function calling
+
+Enable your voice assistant to call external functions and tools:
+
+```ts snippet:ReadmeSampleFunctionCalling
+import { DefaultAzureCredential } from "@azure/identity";
+import { VoiceLiveClient } from "@azure/ai-voicelive";
+
+const credential = new DefaultAzureCredential();
+const endpoint = "https://your-resource.cognitiveservices.azure.com";
+const client = new VoiceLiveClient(endpoint, credential);
+const session = await client.startSession("gpt-4o-mini-realtime-preview");
+
+// Define available functions
+const tools = [
+  {
+    type: "function",
+    name: "get_weather",
+    description: "Get current weather for a location",
+    parameters: {
+      type: "object",
+      properties: {
+        location: {
+          type: "string",
+          description: "The city and state or country",
+        },
+      },
+      required: ["location"],
+    },
+  },
+];
+
+// Configure session with tools
+await session.updateSession({
+  modalities: ["audio", "text"],
+  instructions:
+    "You can help users with weather information. Use the get_weather function when needed.",
+  tools: tools,
+  toolChoice: "auto",
+});
+
+// Handle function calls
+const subscription = session.subscribe({
+  onResponseFunctionCallArgumentsDone: async (event, context) => {
+    if (event.name === "get_weather") {
+      const args = JSON.parse(event.arguments);
+      const weatherData = await getWeatherData(args.location);
+
+      // Send function result back
+      await session.addConversationItem({
+        type: "function_call_output",
+        callId: event.callId,
+        output: JSON.stringify(weatherData),
+      });
+
+      // Request response generation
+      await session.sendEvent({
+        type: "response.create",
+      });
+    }
+  },
+});
+```
+
+## Troubleshooting
+
+### Common errors and exceptions
+
+**Authentication Errors**: If you receive authentication errors, verify that:
+- Your Azure AI Foundry resource is correctly configured
+- Your API key or credential has the necessary permissions
+- The endpoint URL is correct and accessible
+
+**WebSocket Connection Issues**: VoiceLive uses WebSocket connections. Ensure that:
+- Your network allows WebSocket connections
+- Firewall rules permit connections to `*.cognitiveservices.azure.com`
+- Browser policies allow WebSocket and microphone access (for browser usage)
+
+**Audio Issues**: For audio-related problems:
+- Verify microphone permissions in the browser
+- Check that audio formats (PCM16, PCM24) are supported
+- Ensure proper audio context setup for playback
+
+### Logging
+
+Enabling logging may help uncover useful information about failures. In order to see a log of WebSocket messages and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
+
+```ts snippet:SetLogLevel
+import { setLogLevel } from "@azure/logger";
+
+setLogLevel("info");
+```
+
+For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger).
+
+## Next steps
+
+You can find more code samples through the following links:
+
+- [VoiceLive Samples (JavaScript/TypeScript)](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/ai/ai-voicelive/samples)
+- [VoiceLive Test Cases](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/ai/ai-voicelive/test)
+
+## Contributing
+
+If you'd like to contribute to this library, please read the [contributing guide](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) to learn more about how to build and test the code.
+
+[defaultazurecredential]: https://learn.microsoft.com/javascript/api/@azure/identity/defaultazurecredential?view=azure-node-latest
+[managed_identity]: https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview  
+[azure_identity]: https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest

package/dist/browser/auth/credentialHandler.d.ts

@@ -0,0 +1,43 @@
+import type { TokenCredential, KeyCredential } from "@azure/core-auth";
+/**
+ * Union type for supported credential types
+ */
+export type VoiceLiveCredential = TokenCredential | KeyCredential;
+/**
+ * Handles both Azure TokenCredential and KeyCredential authentication for Voice Live service
+ */
+export declare class CredentialHandler {
+    private _accessToken?;
+    private readonly _scope;
+    private readonly _tokenRefreshBuffer;
+    private readonly _credential;
+    private readonly _isApiKey;
+    constructor(credential: VoiceLiveCredential, scope?: string);
+    /**
+     * Gets a valid access token or API key, refreshing if necessary
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Builds the WebSocket URL with authentication
+     */
+    getWebSocketUrl(baseEndpoint: string, apiVersion: string, model?: string): Promise<string>;
+    /**
+     * Gets authentication headers for the WebSocket connection
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    /**
+     * Returns the type of credential being used
+     */
+    get credentialType(): "key" | "token";
+    /**
+     * Returns whether this is using an API key credential
+     */
+    get isApiKey(): boolean;
+    /**
+     * For API key credentials, allows updating the key
+     */
+    updateApiKey(newKey: string): void;
+    private _isTokenValid;
+    private _generateRequestId;
+}
+//# sourceMappingURL=credentialHandler.d.ts.map

package/dist/browser/auth/credentialHandler.js

@@ -0,0 +1,147 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { VoiceLiveAuthenticationError, VoiceLiveErrorCodes } from "../errors/index.js";
+import { logger } from "../logger.js";
+/**
+ * Type guard to check if credential is a KeyCredential
+ */
+function isKeyCredential(credential) {
+    return "key" in credential && typeof credential.key === "string";
+}
+/**
+ * Handles both Azure TokenCredential and KeyCredential authentication for Voice Live service
+ */
+export class CredentialHandler {
+    _accessToken;
+    _scope;
+    _tokenRefreshBuffer = 5 * 60 * 1000; // 5 minutes
+    _credential;
+    _isApiKey;
+    constructor(credential, scope) {
+        this._credential = credential;
+        this._isApiKey = isKeyCredential(credential);
+        // Voice Live specific scope - may need adjustment based on actual service
+        this._scope = scope || "https://cognitiveservices.azure.com/.default";
+        logger.info("CredentialHandler initialized", {
+            credentialType: this._isApiKey ? "KeyCredential" : "TokenCredential",
+            scope: this._scope,
+        });
+    }
+    /**
+     * Gets a valid access token or API key, refreshing if necessary
+     */
+    async getAccessToken() {
+        // For API Key credentials, return the key directly
+        if (this._isApiKey) {
+            const keyCredential = this._credential;
+            logger.info("Using API key for authentication");
+            return keyCredential.key;
+        }
+        // For Token credentials, handle token lifecycle
+        const tokenCredential = this._credential;
+        // Check if current token is still valid
+        if (this._accessToken && this._isTokenValid(this._accessToken)) {
+            return this._accessToken.token;
+        }
+        try {
+            logger.info("Acquiring new access token", { scope: this._scope });
+            // Get new token from credential
+            const tokenResponse = await tokenCredential.getToken(this._scope);
+            if (!tokenResponse) {
+                throw new VoiceLiveAuthenticationError("Failed to acquire access token - credential returned null", VoiceLiveErrorCodes.AuthenticationFailed);
+            }
+            this._accessToken = tokenResponse;
+            logger.info("Successfully acquired access token", {
+                expiresAt: new Date(this._accessToken.expiresOnTimestamp),
+            });
+            return this._accessToken.token;
+        }
+        catch (error) {
+            logger.error("Failed to obtain access token", { error, scope: this._scope });
+            if (error instanceof VoiceLiveAuthenticationError) {
+                throw error;
+            }
+            throw new VoiceLiveAuthenticationError(`Failed to obtain access token: ${error instanceof Error ? error.message : "Unknown error"}`, VoiceLiveErrorCodes.AuthenticationFailed, error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    /**
+     * Builds the WebSocket URL with authentication
+     */
+    async getWebSocketUrl(baseEndpoint, apiVersion, model) {
+        const authValue = await this.getAccessToken();
+        const url = new URL(baseEndpoint);
+        url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+        url.pathname = "/voice-live/realtime"; // Voice Live WebSocket endpoint path
+        url.searchParams.set("api-version", apiVersion);
+        // Add model parameter if provided
+        if (model) {
+            url.searchParams.set("model", model);
+        }
+        // For API keys, add as query parameter
+        if (this._isApiKey) {
+            url.searchParams.set("api-key", authValue);
+        }
+        else {
+            // For tokens, we'll use headers instead of query params
+            // The token will be added in getAuthHeaders()
+        }
+        return url.toString();
+    }
+    /**
+     * Gets authentication headers for the WebSocket connection
+     */
+    async getAuthHeaders() {
+        const authValue = await this.getAccessToken();
+        const headers = {
+            "X-MS-Client-Request-ID": this._generateRequestId(),
+            "User-Agent": "Azure-Voice-Live-SDK-JS/1.0.0",
+        };
+        // Add appropriate authentication header based on credential type
+        if (this._isApiKey) {
+            // For API keys, use the X-API-Key header or similar
+            headers["api-key"] = authValue;
+        }
+        else {
+            // For tokens, use standard Bearer authorization
+            headers["Authorization"] = `Bearer ${authValue}`;
+        }
+        return headers;
+    }
+    /**
+     * Returns the type of credential being used
+     */
+    get credentialType() {
+        return this._isApiKey ? "key" : "token";
+    }
+    /**
+     * Returns whether this is using an API key credential
+     */
+    get isApiKey() {
+        return this._isApiKey;
+    }
+    /**
+     * For API key credentials, allows updating the key
+     */
+    updateApiKey(newKey) {
+        if (!this._isApiKey) {
+            throw new VoiceLiveAuthenticationError("Cannot update API key on TokenCredential", VoiceLiveErrorCodes.InvalidCredentials);
+        }
+        const keyCredential = this._credential;
+        if ("update" in keyCredential && typeof keyCredential.update === "function") {
+            keyCredential.update(newKey);
+            logger.info("API key updated");
+        }
+        else {
+            throw new VoiceLiveAuthenticationError("KeyCredential does not support key updates", VoiceLiveErrorCodes.InvalidCredentials);
+        }
+    }
+    _isTokenValid(token) {
+        const expiresAt = token.expiresOnTimestamp;
+        const now = Date.now();
+        return expiresAt > now + this._tokenRefreshBuffer;
+    }
+    _generateRequestId() {
+        return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    }
+}
+//# sourceMappingURL=credentialHandler.js.map

package/dist/browser/auth/credentialHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentialHandler.js","sourceRoot":"","sources":["../../../src/auth/credentialHandler.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT License.\n\nimport type { TokenCredential, KeyCredential, AccessToken } from \"@azure/core-auth\";\nimport { VoiceLiveAuthenticationError, VoiceLiveErrorCodes } from \"../errors/index.js\";\nimport { logger } from \"../logger.js\";\n\n/**\n * Union type for supported credential types\n */\nexport type VoiceLiveCredential = TokenCredential | KeyCredential;\n\n/**\n * Type guard to check if credential is a KeyCredential\n */\nfunction isKeyCredential(credential: VoiceLiveCredential): credential is KeyCredential {\n  return \"key\" in credential && typeof (credential as KeyCredential).key === \"string\";\n}\n\n/**\n * Handles both Azure TokenCredential and KeyCredential authentication for Voice Live service\n */\nexport class CredentialHandler {\n  private _accessToken?: AccessToken;\n  private readonly _scope: string;\n  private readonly _tokenRefreshBuffer = 5 * 60 * 1000; // 5 minutes\n  private readonly _credential: VoiceLiveCredential;\n  private readonly _isApiKey: boolean;\n\n  constructor(credential: VoiceLiveCredential, scope?: string) {\n    this._credential = credential;\n    this._isApiKey = isKeyCredential(credential);\n\n    // Voice Live specific scope - may need adjustment based on actual service\n    this._scope = scope || \"https://cognitiveservices.azure.com/.default\";\n\n    logger.info(\"CredentialHandler initialized\", {\n      credentialType: this._isApiKey ? \"KeyCredential\" : \"TokenCredential\",\n      scope: this._scope,\n    });\n  }\n\n  /**\n   * Gets a valid access token or API key, refreshing if necessary\n   */\n  async getAccessToken(): Promise<string> {\n    // For API Key credentials, return the key directly\n    if (this._isApiKey) {\n      const keyCredential = this._credential as KeyCredential;\n      logger.info(\"Using API key for authentication\");\n      return keyCredential.key;\n    }\n\n    // For Token credentials, handle token lifecycle\n    const tokenCredential = this._credential as TokenCredential;\n\n    // Check if current token is still valid\n    if (this._accessToken && this._isTokenValid(this._accessToken)) {\n      return this._accessToken.token;\n    }\n\n    try {\n      logger.info(\"Acquiring new access token\", { scope: this._scope });\n\n      // Get new token from credential\n      const tokenResponse = await tokenCredential.getToken(this._scope);\n\n      if (!tokenResponse) {\n        throw new VoiceLiveAuthenticationError(\n          \"Failed to acquire access token - credential returned null\",\n          VoiceLiveErrorCodes.AuthenticationFailed,\n        );\n      }\n\n      this._accessToken = tokenResponse;\n\n      logger.info(\"Successfully acquired access token\", {\n        expiresAt: new Date(this._accessToken.expiresOnTimestamp),\n      });\n\n      return this._accessToken.token;\n    } catch (error) {\n      logger.error(\"Failed to obtain access token\", { error, scope: this._scope });\n\n      if (error instanceof VoiceLiveAuthenticationError) {\n        throw error;\n      }\n\n      throw new VoiceLiveAuthenticationError(\n        `Failed to obtain access token: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        VoiceLiveErrorCodes.AuthenticationFailed,\n        error instanceof Error ? error : new Error(String(error)),\n      );\n    }\n  }\n\n  /**\n   * Builds the WebSocket URL with authentication\n   */\n  async getWebSocketUrl(baseEndpoint: string, apiVersion: string, model?: string): Promise<string> {\n    const authValue = await this.getAccessToken();\n\n    const url = new URL(baseEndpoint);\n    url.protocol = url.protocol === \"https:\" ? \"wss:\" : \"ws:\";\n    url.pathname = \"/voice-live/realtime\"; // Voice Live WebSocket endpoint path\n    url.searchParams.set(\"api-version\", apiVersion);\n\n    // Add model parameter if provided\n    if (model) {\n      url.searchParams.set(\"model\", model);\n    }\n\n    // For API keys, add as query parameter\n    if (this._isApiKey) {\n      url.searchParams.set(\"api-key\", authValue);\n    } else {\n      // For tokens, we'll use headers instead of query params\n      // The token will be added in getAuthHeaders()\n    }\n\n    return url.toString();\n  }\n\n  /**\n   * Gets authentication headers for the WebSocket connection\n   */\n  async getAuthHeaders(): Promise<Record<string, string>> {\n    const authValue = await this.getAccessToken();\n\n    const headers: Record<string, string> = {\n      \"X-MS-Client-Request-ID\": this._generateRequestId(),\n      \"User-Agent\": \"Azure-Voice-Live-SDK-JS/1.0.0\",\n    };\n\n    // Add appropriate authentication header based on credential type\n    if (this._isApiKey) {\n      // For API keys, use the X-API-Key header or similar\n      headers[\"api-key\"] = authValue;\n    } else {\n      // For tokens, use standard Bearer authorization\n      headers[\"Authorization\"] = `Bearer ${authValue}`;\n    }\n\n    return headers;\n  }\n\n  /**\n   * Returns the type of credential being used\n   */\n  get credentialType(): \"key\" | \"token\" {\n    return this._isApiKey ? \"key\" : \"token\";\n  }\n\n  /**\n   * Returns whether this is using an API key credential\n   */\n  get isApiKey(): boolean {\n    return this._isApiKey;\n  }\n\n  /**\n   * For API key credentials, allows updating the key\n   */\n  updateApiKey(newKey: string): void {\n    if (!this._isApiKey) {\n      throw new VoiceLiveAuthenticationError(\n        \"Cannot update API key on TokenCredential\",\n        VoiceLiveErrorCodes.InvalidCredentials,\n      );\n    }\n\n    const keyCredential = this._credential as KeyCredential;\n    if (\"update\" in keyCredential && typeof keyCredential.update === \"function\") {\n      keyCredential.update(newKey);\n      logger.info(\"API key updated\");\n    } else {\n      throw new VoiceLiveAuthenticationError(\n        \"KeyCredential does not support key updates\",\n        VoiceLiveErrorCodes.InvalidCredentials,\n      );\n    }\n  }\n\n  private _isTokenValid(token: AccessToken): boolean {\n    const expiresAt = token.expiresOnTimestamp;\n    const now = Date.now();\n    return expiresAt > now + this._tokenRefreshBuffer;\n  }\n\n  private _generateRequestId(): string {\n    return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;\n  }\n}\n"]}

package/dist/browser/errors/connectionErrors.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Error codes for Voice Live WebSocket operations
+ */
+export declare enum VoiceLiveErrorCodes {
+    ConnectionFailed = "CONNECTION_FAILED",
+    ConnectionTimeout = "CONNECTION_TIMEOUT",
+    ConnectionLost = "CONNECTION_LOST",
+    AlreadyConnected = "ALREADY_CONNECTED",
+    NotConnected = "NOT_CONNECTED",
+    WebSocketError = "WEBSOCKET_ERROR",
+    AuthenticationFailed = "AUTHENTICATION_FAILED",
+    InvalidCredentials = "INVALID_CREDENTIALS",
+    Unauthorized = "UNAUTHORIZED",
+    Forbidden = "FORBIDDEN",
+    InvalidMessage = "INVALID_MESSAGE",
+    MessageTooLarge = "MESSAGE_TOO_LARGE",
+    ProtocolError = "PROTOCOL_ERROR",
+    BufferOverflow = "BUFFER_OVERFLOW",
+    OperationCancelled = "OPERATION_CANCELLED",
+    InvalidState = "INVALID_STATE"
+}
+/**
+ * Base error class for Voice Live WebSocket operations
+ */
+export declare class VoiceLiveConnectionError extends Error {
+    /** Error code identifying the specific error type */
+    readonly code: string;
+    /** Context information about where the error occurred */
+    readonly context: string;
+    /** Indicates whether this error is potentially recoverable */
+    readonly recoverable: boolean;
+    /** The original error that caused this error, if any */
+    readonly cause?: Error;
+    /** Timestamp when the error occurred */
+    readonly timestamp: Date;
+    constructor(message: string, code: string, context?: string, recoverable?: boolean, cause?: Error);
+}
+/**
+ * Authentication error class for Voice Live operations
+ */
+export declare class VoiceLiveAuthenticationError extends VoiceLiveConnectionError {
+    constructor(message: string, code: string, cause?: Error);
+}
+/**
+ * Protocol error class for Voice Live message operations
+ */
+export declare class VoiceLiveProtocolError extends VoiceLiveConnectionError {
+    constructor(message: string, code: string, cause?: Error);
+}
+/**
+ * General Voice Live error class
+ */
+export declare class VoiceLiveError extends VoiceLiveConnectionError {
+    constructor(message: string, code: string, context?: string, recoverable?: boolean, cause?: Error);
+}
+/**
+ * Classifies a WebSocket close event and returns appropriate error
+ */
+export declare function classifyWebSocketClose(code: number, reason: string): VoiceLiveConnectionError;
+/**
+ * Classifies connection errors
+ */
+export declare function classifyConnectionError(error: VoiceLiveConnectionError | Error | unknown): VoiceLiveConnectionError;
+/**
+ * Classifies protocol errors
+ */
+export declare function classifyProtocolError(error: Error, messageType: string): VoiceLiveProtocolError;
+//# sourceMappingURL=connectionErrors.d.ts.map