@anganyai/voice-sdk 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,1708 @@
+/**
+ * Core type definitions for Angany Voice SDK
+ */
+/**
+ * SDK configuration options
+ */
+interface VoiceConfig {
+    /**
+     * The base URL of the Angany API
+     * @default 'https://api.angany.ai'
+     */
+    apiUrl: string;
+    /**
+     * The OIDC issuer URL
+     * @default Same as apiUrl
+     */
+    issuer?: string;
+    /**
+     * Enable debug mode for detailed logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Logging level
+     * @default 'warn'
+     */
+    logLevel?: LogLevel;
+    /**
+     * Custom logger instance
+     */
+    logger?: Logger;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Retry configuration
+     */
+    retry?: RetryConfig;
+    /**
+     * Custom headers to include in all requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * Platform-specific configuration
+     */
+    platform?: PlatformConfig;
+}
+/**
+ * Log levels
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Logger interface
+ */
+interface Logger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * Retry configuration
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxAttempts?: number;
+    /**
+     * Initial delay in milliseconds
+     * @default 1000
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay in milliseconds
+     * @default 30000
+     */
+    maxDelay?: number;
+    /**
+     * Backoff multiplier
+     * @default 2
+     */
+    multiplier?: number;
+    /**
+     * Jitter factor (0-1)
+     * @default 0.1
+     */
+    jitter?: number;
+}
+/**
+ * Platform-specific configuration
+ */
+interface PlatformConfig {
+    /**
+     * React Native specific config
+     */
+    reactNative?: {
+        /**
+         * InCallManager configuration
+         */
+        inCallManager?: Record<string, unknown>;
+    };
+    /**
+     * Node.js specific config
+     */
+    node?: {
+        /**
+         * HTTP agent configuration
+         */
+        agent?: unknown;
+    };
+    /**
+     * Web specific config
+     */
+    web?: {
+        /**
+         * WebRTC constraints
+         */
+        rtcConfiguration?: RTCConfiguration;
+    };
+}
+/**
+ * Voice resource information
+ */
+interface VoiceResource {
+    /**
+     * Unique identifier for the resource
+     */
+    id: string;
+    /**
+     * Display name of the resource
+     */
+    name: string;
+    /**
+     * Description of the resource
+     */
+    description?: string;
+    /**
+     * Resource type
+     */
+    type: 'agent' | 'assistant' | 'custom';
+    /**
+     * Resource capabilities
+     */
+    capabilities?: string[];
+    /**
+     * Resource metadata
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Whether the resource is currently available
+     */
+    available: boolean;
+    /**
+     * Resource configuration
+     */
+    config?: ResourceConfig;
+}
+/**
+ * Resource configuration
+ */
+interface ResourceConfig {
+    /**
+     * SIP extension for this resource
+     */
+    extension?: string;
+    /**
+     * Supported languages
+     */
+    languages?: string[];
+    /**
+     * Voice configuration
+     */
+    voice?: {
+        /**
+         * Voice ID
+         */
+        id?: string;
+        /**
+         * Voice settings
+         */
+        settings?: Record<string, unknown>;
+    };
+    /**
+     * Custom configuration
+     */
+    custom?: Record<string, unknown>;
+}
+
+/**
+ * Simple event emitter implementation for the SDK
+ *
+ * Provides a lightweight event system without external dependencies.
+ * Supports typed events for better developer experience.
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   data: [value: string];
+ *   error: [error: Error];
+ *   ready: [];
+ * }
+ *
+ * class MyClass extends EventEmitter<MyEvents> {
+ *   doSomething() {
+ *     this.emit('data', 'hello');
+ *     this.emit('error', new Error('oops'));
+ *     this.emit('ready');
+ *   }
+ * }
+ * ```
+ */
+declare class EventEmitter<T extends Record<string, unknown[]>> {
+    private listeners;
+    /**
+     * Register an event listener
+     *
+     * @param event - Event name
+     * @param handler - Event handler function
+     *
+     * @example
+     * ```typescript
+     * emitter.on('data', (value) => {
+     *   console.log('Received:', value);
+     * });
+     * ```
+     */
+    on<K extends keyof T>(event: K, handler: (...args: T[K]) => void): void;
+    /**
+     * Unregister an event listener
+     *
+     * @param event - Event name
+     * @param handler - Event handler function to remove
+     *
+     * @example
+     * ```typescript
+     * const handler = (value) => console.log(value);
+     * emitter.on('data', handler);
+     * emitter.off('data', handler);
+     * ```
+     */
+    off<K extends keyof T>(event: K, handler: (...args: T[K]) => void): void;
+    /**
+     * Register a one-time event listener
+     *
+     * The handler will be automatically removed after the first call.
+     *
+     * @param event - Event name
+     * @param handler - Event handler function
+     *
+     * @example
+     * ```typescript
+     * emitter.once('ready', () => {
+     *   console.log('Ready! This will only fire once');
+     * });
+     * ```
+     */
+    once<K extends keyof T>(event: K, handler: (...args: T[K]) => void): void;
+    /**
+     * Emit an event
+     *
+     * Calls all registered handlers for the event in the order they were registered.
+     *
+     * @param event - Event name
+     * @param args - Arguments to pass to event handlers
+     *
+     * @example
+     * ```typescript
+     * emitter.emit('data', 'hello world');
+     * emitter.emit('error', new Error('Something went wrong'));
+     * ```
+     */
+    emit<K extends keyof T>(event: K, ...args: T[K]): void;
+    /**
+     * Remove all listeners for an event or all events
+     *
+     * @param event - Event name (optional). If not provided, removes all listeners.
+     *
+     * @example
+     * ```typescript
+     * // Remove all listeners for 'data' event
+     * emitter.removeAllListeners('data');
+     *
+     * // Remove all listeners for all events
+     * emitter.removeAllListeners();
+     * ```
+     */
+    removeAllListeners(event?: keyof T): void;
+    /**
+     * Get the number of listeners for an event
+     *
+     * @param event - Event name
+     * @returns Number of registered listeners
+     *
+     * @example
+     * ```typescript
+     * const count = emitter.listenerCount('data');
+     * console.log(`There are ${count} data listeners`);
+     * ```
+     */
+    listenerCount(event: keyof T): number;
+    /**
+     * Get all event names that have listeners
+     *
+     * @returns Array of event names
+     *
+     * @example
+     * ```typescript
+     * const events = emitter.eventNames();
+     * console.log('Active events:', events);
+     * ```
+     */
+    eventNames(): (keyof T)[];
+}
+
+/**
+ * Authentication type definitions for Angany Voice SDK
+ */
+/**
+ * Base authentication options
+ */
+interface AuthOptions {
+    /**
+     * Authentication method
+     */
+    method: 'frontend' | 'backend' | 'service-account';
+    /**
+     * Token refresh buffer in seconds
+     * @default 300 (5 minutes)
+     */
+    refreshBufferSeconds?: number;
+    /**
+     * Enable automatic token refresh
+     * @default true
+     */
+    autoRefresh?: boolean;
+}
+/**
+ * Frontend authentication options
+ */
+interface FrontendAuthOptions extends AuthOptions {
+    method: 'frontend';
+    /**
+     * OAuth redirect URI
+     * If not provided, will use popup flow (not supported by all providers)
+     */
+    redirectUri?: string;
+    /**
+     * OAuth scopes to request
+     * @default ['openid', 'profile', 'offline_access']
+     */
+    scopes?: string[];
+    /**
+     * Storage preference for credentials
+     * @default 'localStorage'
+     */
+    storage?: 'localStorage' | 'sessionStorage' | 'memory';
+}
+/**
+ * Backend authentication options
+ */
+interface BackendAuthOptions extends AuthOptions {
+    method: 'backend';
+    redirectUri?: string;
+    postLogoutRedirectUris?: string[];
+    branding?: BrandingOptions;
+    scopes?: string[];
+    autoRefresh?: boolean;
+    refreshBufferSeconds?: number;
+}
+/**
+ * Service account authentication options
+ */
+interface ServiceAccountAuthOptions extends AuthOptions {
+    method: 'service-account';
+    /**
+     * Service account credentials
+     */
+    credentials: ServiceAccountCredentials;
+    /**
+     * OAuth scopes to request
+     * @default ['api:voice', 'api:conversation']
+     */
+    scopes?: string[];
+}
+/**
+ * Service account credentials
+ */
+interface ServiceAccountCredentials {
+    /**
+     * Service account ID
+     */
+    clientId: string;
+    /**
+     * Service account secret
+     */
+    clientSecret: string;
+    /**
+     * Optional key ID
+     */
+    keyId?: string;
+    /**
+     * Optional private key for JWT assertion
+     */
+    privateKey?: string;
+}
+/**
+ * OAuth client credentials (for dynamic registration)
+ */
+interface ClientCredentials {
+    /**
+     * Client ID
+     */
+    clientId: string;
+    /**
+     * Client secret (if applicable)
+     */
+    clientSecret?: string;
+    /**
+     * Registration access token
+     */
+    registrationAccessToken?: string;
+    /**
+     * Registration client URI
+     */
+    registrationClientUri?: string;
+    /**
+     * When the credentials were created
+     */
+    createdAt: Date;
+    /**
+     * When the credentials expire (if applicable)
+     */
+    expiresAt?: Date;
+    /**
+     * Token endpoint authentication method
+     */
+    tokenEndpointAuthMethod?: string;
+}
+/**
+ * Token set
+ */
+interface TokenSet {
+    /**
+     * Access token
+     */
+    accessToken: string;
+    /**
+     * Refresh token (if available)
+     */
+    refreshToken?: string;
+    /**
+     * ID token (if available)
+     */
+    idToken?: string;
+    /**
+     * Token type
+     * @default 'Bearer'
+     */
+    tokenType: string;
+    /**
+     * Token expiration time (seconds from now)
+     */
+    expiresIn?: number;
+    /**
+     * Absolute expiration timestamp
+     */
+    expiresAt?: Date;
+    /**
+     * Granted scopes
+     */
+    scope?: string;
+}
+/**
+ * Authentication status
+ */
+interface AuthStatus {
+    /**
+     * Whether the user is authenticated
+     */
+    authenticated: boolean;
+    /**
+     * Current authentication method
+     */
+    method?: 'frontend' | 'backend' | 'service-account';
+    /**
+     * Current token set
+     */
+    tokens?: TokenSet;
+    /**
+     * User information
+     */
+    user?: UserInfo;
+    /**
+     * Authentication error (if any)
+     */
+    error?: AuthError;
+    /**
+     * Authentication state
+     */
+    state: AuthState;
+    /**
+     * When the auth status was last updated
+     */
+    updatedAt: Date;
+    /**
+     * OAuth client credentials
+     */
+    clientCredentials?: ClientCredentials;
+    /**
+     * When tokens expire
+     */
+    expiresAt?: Date;
+    /**
+     * When tokens will be refreshed (if auto-refresh is enabled)
+     */
+    refreshAt?: Date;
+}
+/**
+ * Authentication state
+ */
+type AuthState = 'unauthenticated' | 'authenticating' | 'authenticated' | 'refreshing' | 'error';
+/**
+ * User information
+ */
+interface UserInfo {
+    /**
+     * User ID
+     */
+    id: string;
+    /**
+     * Username
+     */
+    username?: string;
+    /**
+     * Email address
+     */
+    email?: string;
+    /**
+     * Display name
+     */
+    name?: string;
+    /**
+     * User avatar URL
+     */
+    picture?: string;
+    /**
+     * User roles
+     */
+    roles?: string[];
+    /**
+     * User permissions
+     */
+    permissions?: string[];
+    /**
+     * Additional user attributes
+     */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Authentication error
+ */
+interface AuthError {
+    /**
+     * Error code
+     */
+    code: string;
+    /**
+     * Error message
+     */
+    message: string;
+    /**
+     * Error details
+     */
+    details?: Record<string, unknown>;
+    /**
+     * When the error occurred
+     */
+    timestamp: Date;
+}
+/**
+ * Credential rotation callback
+ */
+type CredentialRotationCallback = () => Promise<{
+    sip: {
+        username: string;
+        password: string;
+        realm?: string;
+        websocketUrl?: string;
+        uris?: string[];
+    };
+    apiToken?: string;
+    expiresAt: Date | string;
+    expiresIn: number;
+}>;
+/**
+ * Authentication event types
+ */
+interface AuthEvents extends Record<string, unknown[]> {
+    /**
+     * Emitted when authentication state changes
+     */
+    stateChange: [state: AuthState, previousState: AuthState];
+    /**
+     * Emitted when tokens are refreshed
+     */
+    tokenRefresh: [tokens: TokenSet];
+    /**
+     * Emitted when authentication fails
+     */
+    error: [error: AuthError];
+    /**
+     * Emitted when user logs out
+     */
+    logout: [];
+    /**
+     * Emitted when tokens are about to expire
+     */
+    tokenExpiring: [expiresIn: number];
+    /**
+     * Emitted when ephemeral credentials are about to expire
+     */
+    credentialsExpiring: [expiresIn: number];
+    /**
+     * Emitted when ephemeral credentials have been refreshed
+     */
+    credentialsRefreshed: [
+        credentials: {
+            sip: {
+                username: string;
+                password: string;
+                realm?: string;
+                websocketUrl?: string;
+                uris?: string[];
+            };
+            apiToken?: string;
+            expiresAt: Date;
+            expiresIn: number;
+        }
+    ];
+    /**
+     * Emitted when credential rotation fails
+     */
+    credentialRotationFailed: [error: Error];
+}
+/**
+ * Application branding options for OAuth consent page
+ */
+interface BrandingOptions {
+    /**
+     * Application name
+     */
+    applicationName?: string;
+    /**
+     * URL to application icon (recommended: 512x512px)
+     */
+    applicationIcon?: string;
+    /**
+     * Brief description of your application
+     */
+    applicationDescription?: string;
+    /**
+     * Application homepage URL
+     */
+    homepageUrl?: string;
+    /**
+     * Terms of service URL
+     */
+    termsUrl?: string;
+    /**
+     * Privacy policy URL
+     */
+    privacyUrl?: string;
+}
+
+/**
+ * Credential manager for the Angany Voice SDK
+ *
+ * Handles client credentials registration and ephemeral credentials for WebRTC connections.
+ */
+
+interface EphemeralCredentials {
+    sip: {
+        username: string;
+        password: string;
+        realm?: string;
+        websocketUrl?: string;
+        uris?: string[];
+    };
+    apiToken?: string | undefined;
+    expiresAt: Date;
+    expiresIn: number;
+    ice_servers?: RTCIceServer[];
+}
+
+/**
+ * Authentication manager for the Angany Voice SDK
+ *
+ * Handles OAuth2 authentication flows, token management, and ephemeral credentials
+ * for WebRTC connections. Uses the certified openid-client library for all OAuth2/OIDC operations.
+ *
+ * Supports multiple authentication patterns:
+ * - Frontend (SPA) authentication with redirect or popup
+ * - Backend authentication with dynamic client registration
+ * - Service account authentication
+ *
+ * This class acts as a facade over specialized authentication components following SOLID principles.
+ */
+
+/**
+ * Manages authentication for the Angany Voice SDK using openid-client
+ *
+ * @example Frontend Authentication
+ * ```typescript
+ * const auth = new AuthManager('https://api.angany.ai');
+ * await auth.authenticateFrontend({
+ *   redirectUri: 'https://app.example.com/callback'
+ * });
+ * ```
+ *
+ * @example Backend Authentication with Dynamic Registration
+ * ```typescript
+ * const auth = new AuthManager('https://api.angany.ai');
+ * const result = await auth.authenticateBackend({
+ *   branding: {
+ *     applicationName: 'My App',
+ *     applicationIcon: 'https://example.com/icon.png'
+ *   }
+ * });
+ * // Save result.clientCredentials for reuse
+ * ```
+ */
+declare class AuthManager extends EventEmitter<AuthEvents> {
+    private readonly logger;
+    private state;
+    private options;
+    private readonly issuer;
+    private readonly storageManager;
+    private readonly tokenManager;
+    private readonly credentialManager;
+    private readonly oauthClient;
+    private credentialRotationCallback?;
+    private credentialRotationTimeout?;
+    private credentialExpiryWarningThreshold;
+    constructor(apiUrl: string, issuer?: string);
+    /**
+     * Try to restore a previous session from localStorage
+     * This should be called on app startup to restore authentication state
+     *
+     * @returns true if session was restored successfully, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const auth = new AuthManager('https://api.angany.ai');
+     * const restored = await auth.tryRestoreSession();
+     * if (restored) {
+     *   console.log('Session restored, user is authenticated');
+     * } else {
+     *   console.log('No session to restore, redirect to login');
+     * }
+     * ```
+     */
+    tryRestoreSession(): Promise<boolean>;
+    /**
+     * Authenticate using frontend flow (SPA)
+     */
+    authenticateFrontend(options?: Partial<FrontendAuthOptions>): Promise<void>;
+    /**
+     * Authenticate using backend flow
+     */
+    authenticateBackend(options?: Partial<BackendAuthOptions>): Promise<{
+        clientCredentials: ClientCredentials;
+        authUrl?: string;
+    }>;
+    /**
+     * Authenticate using service account (client credentials)
+     */
+    authenticateServiceAccount(options: ServiceAccountAuthOptions): Promise<void>;
+    /**
+     * Use existing client credentials
+     */
+    useExistingCredentials(credentials: ClientCredentials, options?: {
+        redirectUri?: string;
+        scope?: string;
+    }): Promise<void>;
+    /**
+     * Get authorization URL for OAuth flow
+     */
+    getAuthorizationUrl(): Promise<{
+        url: string;
+        codeVerifier: string;
+        state: string;
+    }>;
+    /**
+     * Set PKCE code verifier (for backend flows)
+     */
+    setCodeVerifier(codeVerifier: string): void;
+    /**
+     * Handle OAuth callback
+     */
+    handleCallback(code: string, state: string, codeVerifier?: string): Promise<{
+        success: boolean;
+        user?: UserInfo;
+    }>;
+    /**
+     * Check if ephemeral credentials are available and valid
+     */
+    hasValidEphemeralCredentials(): boolean;
+    /**
+     * Get cached ephemeral credentials (if valid)
+     */
+    getCachedEphemeralCredentials(): EphemeralCredentials | undefined;
+    /**
+     * Get current authentication status
+     */
+    getAuthStatus(): AuthStatus;
+    /**
+     * Get current tokens
+     */
+    getTokens(): TokenSet | undefined;
+    /**
+     * Get access token
+     */
+    getAccessToken(): Promise<string | undefined>;
+    /**
+     * Refresh tokens
+     */
+    refreshTokens(): Promise<TokenSet>;
+    /**
+     * Set ephemeral credentials for WebRTC connections
+     */
+    setEphemeralCredentials(credentials: {
+        sip: {
+            username: string;
+            password: string;
+            realm?: string;
+            websocketUrl?: string;
+            uris?: string[];
+        };
+        apiToken?: string;
+        expiresAt: Date | string;
+        expiresIn: number;
+    }): void;
+    /**
+     * Set OAuth access token for API calls (hybrid approach)
+     */
+    setOAuthAccessToken(accessToken: string): void;
+    /**
+     * Get ephemeral credentials for a specific user (admin function)
+     */
+    getEphemeralCredentialsForUser(userAccessToken: string): Promise<EphemeralCredentials>;
+    /**
+     * Get ephemeral credentials for WebRTC connections
+     */
+    getEphemeralCredentials(): Promise<EphemeralCredentials>;
+    /**
+     * Renew ephemeral credentials
+     */
+    renewEphemeralCredentials(): Promise<void>;
+    /**
+     * Set credential rotation callback
+     * This callback will be called when credentials are about to expire
+     */
+    setCredentialRotationCallback(callback: CredentialRotationCallback): void;
+    /**
+     * Clear credential rotation callback
+     */
+    clearCredentialRotationCallback(): void;
+    /**
+     * Set credential expiry warning threshold (in seconds before expiry)
+     */
+    setCredentialExpiryWarningThreshold(seconds: number): void;
+    /**
+     * Schedule credential rotation based on actual expiry time
+     */
+    private scheduleCredentialRotation;
+    /**
+     * Clear credential rotation timeout
+     */
+    private clearCredentialRotationTimeout;
+    /**
+     * Perform credential rotation
+     */
+    private performCredentialRotation;
+    /**
+     * Logout user
+     */
+    logout(options?: {
+        clearStoredClient?: boolean;
+        redirectToProvider?: boolean;
+        postLogoutRedirectUri?: string;
+    }): Promise<string | void>;
+    /**
+     * Initialize backend authentication (legacy method)
+     */
+    initializeBackend(options: BackendAuthOptions & {
+        redirectUri?: string;
+        scope?: string;
+    }): Promise<{
+        clientId?: string;
+    }>;
+    /**
+     * Restore tokens from external source
+     */
+    restoreTokens(tokens: TokenSet): void;
+    /**
+     * Set authentication state
+     */
+    private setState;
+}
+
+/**
+ * Conversation type definitions for Angany Voice SDK
+ */
+
+/**
+ * Conversation options
+ */
+interface ConversationOptions {
+    /**
+     * Voice resource ID or name
+     */
+    resource: string;
+    /**
+     * Conversation metadata
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Audio configuration
+     */
+    audio?: AudioConfig;
+    /**
+     * Enable automatic reconnection
+     * @default true
+     */
+    autoReconnect?: boolean;
+    /**
+     * Maximum reconnection attempts
+     * @default 5
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Reconnection delay in milliseconds
+     * @default 1000
+     */
+    reconnectDelay?: number;
+    /**
+     * Enable echo cancellation
+     * @default true
+     */
+    echoCancellation?: boolean;
+    /**
+     * Enable noise suppression
+     * @default true
+     */
+    noiseSuppression?: boolean;
+    /**
+     * Enable automatic gain control
+     * @default true
+     */
+    autoGainControl?: boolean;
+    /**
+     * Custom SIP headers
+     */
+    sipHeaders?: Record<string, string>;
+    /**
+     * Conversation timeout in milliseconds
+     * @default 3600000 (1 hour)
+     */
+    timeout?: number;
+}
+/**
+ * Audio configuration
+ */
+interface AudioConfig {
+    /**
+     * Input device ID
+     */
+    inputDeviceId?: string;
+    /**
+     * Output device ID
+     */
+    outputDeviceId?: string;
+    /**
+     * Sample rate
+     * @default 48000
+     */
+    sampleRate?: number;
+    /**
+     * Audio codec preferences
+     */
+    codecs?: AudioCodec[];
+    /**
+     * Enable stereo
+     * @default false
+     */
+    stereo?: boolean;
+    /**
+     * Audio constraints
+     */
+    constraints?: MediaTrackConstraints;
+}
+/**
+ * Audio codec
+ */
+type AudioCodec = 'opus' | 'PCMU' | 'PCMA' | 'G722' | 'iLBC' | 'VP8';
+/**
+ * Conversation state
+ */
+type ConversationState = 'idle' | 'connecting' | 'connected' | 'active' | 'held' | 'muted' | 'disconnecting' | 'disconnected' | 'failed' | 'reconnecting' | 'error';
+/**
+ * Conversation status
+ */
+interface ConversationStatus {
+    /**
+     * Current state
+     */
+    state: ConversationState;
+    /**
+     * Conversation ID
+     */
+    id?: string;
+    /**
+     * SIP call ID
+     */
+    callId?: string;
+    /**
+     * Resource information
+     */
+    resource?: VoiceResource;
+    /**
+     * Start time
+     */
+    startTime?: Date;
+    /**
+     * End time
+     */
+    endTime?: Date;
+    /**
+     * Duration in seconds
+     */
+    duration?: number;
+    /**
+     * Whether the agent is muted
+     */
+    agentMuted: boolean;
+    /**
+     * Whether the user is muted
+     */
+    userMuted: boolean;
+    /**
+     * Connection quality
+     */
+    quality?: ConnectionQuality;
+    /**
+     * Error information
+     */
+    error?: ConversationError$1;
+    /**
+     * Conversation metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Connection quality
+ */
+interface ConnectionQuality {
+    /**
+     * Overall quality score (0-100)
+     */
+    score: number;
+    /**
+     * Quality level
+     */
+    level: 'excellent' | 'good' | 'fair' | 'poor';
+    /**
+     * Network statistics
+     */
+    stats?: NetworkStats;
+}
+/**
+ * Network statistics
+ */
+interface NetworkStats {
+    /**
+     * Round-trip time in milliseconds
+     */
+    rtt?: number;
+    /**
+     * Packet loss percentage
+     */
+    packetLoss?: number;
+    /**
+     * Jitter in milliseconds
+     */
+    jitter?: number;
+    /**
+     * Bandwidth usage in kbps
+     */
+    bandwidth?: {
+        upload?: number;
+        download?: number;
+    };
+}
+/**
+ * Transcription event
+ */
+interface TranscriptionEvent {
+    /**
+     * Event ID
+     */
+    id: string;
+    /**
+     * Event type
+     */
+    type: 'partial' | 'final';
+    /**
+     * Speaker role
+     */
+    role: 'user' | 'agent';
+    /**
+     * Transcribed text
+     */
+    text: string;
+    /**
+     * Timestamp
+     */
+    timestamp: Date;
+    /**
+     * Duration in seconds
+     */
+    duration?: number;
+    /**
+     * Confidence score (0-1)
+     */
+    confidence?: number;
+    /**
+     * Language code
+     */
+    language?: string;
+    /**
+     * Alternative transcriptions
+     */
+    alternatives?: TranscriptionAlternative[];
+    /**
+     * Additional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Transcription alternative
+ */
+interface TranscriptionAlternative {
+    /**
+     * Alternative text
+     */
+    text: string;
+    /**
+     * Confidence score (0-1)
+     */
+    confidence: number;
+}
+/**
+ * Speak options
+ */
+interface SpeakOptions {
+    /**
+     * Whether to interrupt current speech
+     * @default false
+     */
+    interrupt?: boolean;
+    /**
+     * Priority level
+     * @default 'normal'
+     */
+    priority?: 'low' | 'normal' | 'high' | 'urgent';
+    /**
+     * Callback when speech starts
+     */
+    onStart?: () => void;
+    /**
+     * Callback when speech ends
+     */
+    onEnd?: () => void;
+    /**
+     * Callback on error
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Custom metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Conversation error
+ */
+interface ConversationError$1 {
+    /**
+     * Error code
+     */
+    code: string;
+    /**
+     * Error message
+     */
+    message: string;
+    /**
+     * Error type
+     */
+    type: 'network' | 'permission' | 'resource' | 'timeout' | 'unknown';
+    /**
+     * Whether the error is recoverable
+     */
+    recoverable: boolean;
+    /**
+     * Error details
+     */
+    details?: Record<string, unknown>;
+    /**
+     * Original error
+     */
+    cause?: Error;
+}
+/**
+ * Conversation events
+ */
+interface ConversationEvents extends Record<string, unknown[]> {
+    /**
+     * Emitted when state changes
+     */
+    stateChange: [state: ConversationState, previousState: ConversationState];
+    /**
+     * Emitted when connected
+     */
+    connected: [];
+    /**
+     * Emitted when disconnected
+     */
+    disconnected: [reason?: string];
+    /**
+     * Emitted on transcription
+     */
+    transcription: [
+        event: {
+            speaker: 'user' | 'agent';
+            text: string;
+            timestamp: Date;
+            isFinal: boolean;
+        }
+    ];
+    /**
+     * Emitted on error
+     */
+    error: [error: Error];
+    /**
+     * Emitted when agent is muted/unmuted
+     */
+    agentMuted: [muted: boolean];
+    /**
+     * Emitted when user is muted/unmuted
+     */
+    userMuted: [muted: boolean];
+    /**
+     * Emitted when connection quality changes
+     */
+    qualityChange: [quality: ConnectionQuality];
+    /**
+     * Emitted when reconnecting
+     */
+    reconnecting: [attempt: number];
+    /**
+     * Emitted when reconnected
+     */
+    reconnected: [];
+    /**
+     * Emitted when conversation ends
+     */
+    ended: [summary: {
+        duration: number;
+    }];
+    /**
+     * Emitted with audio level updates
+     */
+    audioLevel: [level: number];
+}
+
+/**
+ * Conversation management
+ */
+
+/**
+ * Represents an active voice conversation
+ */
+declare class Conversation extends EventEmitter<ConversationEvents> {
+    private logger;
+    private id;
+    private state;
+    private options;
+    private agentMuted;
+    private userMuted;
+    private startTime?;
+    private endTime?;
+    private apiUrl;
+    private authManager;
+    private sipManager;
+    private transcriptionService;
+    private apiService;
+    private callId?;
+    private ephemeralCredentials?;
+    private accessToken?;
+    constructor(id: string, options: ConversationOptions, authManager: AuthManager, apiUrl: string);
+    /**
+     * Initialize and start the conversation
+     */
+    initialize(): Promise<void>;
+    /**
+     * Send text to be spoken in the conversation
+     */
+    speak(text: string, options?: {
+        interrupt?: boolean;
+        waitForResponse?: boolean;
+    }): Promise<void>;
+    /**
+     * Mute or unmute the user's microphone
+     */
+    mute(muted: boolean): void;
+    /**
+     * Mute the agent
+     */
+    muteAgent(muted?: boolean): Promise<void>;
+    /**
+     * Unmute the agent (convenience method)
+     */
+    unmuteAgent(): Promise<void>;
+    /**
+     * Check if agent is muted
+     */
+    isAgentMuted(): boolean;
+    /**
+     * Get conversation status
+     */
+    getStatus(): Promise<ConversationStatus>;
+    /**
+     * End the conversation
+     */
+    end(): Promise<void>;
+    /**
+     * Get the conversation ID
+     */
+    getId(): string;
+    /**
+     * Get the current state
+     */
+    getState(): ConversationState;
+    /**
+     * Get the resource ID
+     */
+    get resourceId(): string;
+    /**
+     * Get the conversation status (for compatibility)
+     */
+    get status(): string;
+    /**
+     * Enable audio playback (call after user interaction to bypass autoplay restrictions)
+     */
+    enableAudio(): Promise<void>;
+    /**
+     * Check if audio is playing
+     */
+    isAudioPlaying(): boolean;
+    /**
+     * Set audio volume (0.0 to 1.0)
+     */
+    setVolume(volume: number): void;
+    /**
+     * Mute or unmute the remote audio
+     */
+    setAudioMuted(muted: boolean): void;
+    /**
+     * Get the audio element for external control
+     */
+    getAudioElement(): HTMLAudioElement | undefined;
+    private setState;
+    private setupSipHandlers;
+    private setupTranscriptionHandlers;
+    private cleanup;
+    private extractServerFromUris;
+}
+
+/**
+ * Main entry point for the Angany Voice SDK
+ */
+
+interface VoiceEvents extends Record<string, unknown[]> {
+    /**
+     * Emitted when a conversation is started
+     */
+    conversationStarted: [conversation: Conversation];
+    /**
+     * Emitted when a conversation ends
+     */
+    conversationEnded: [conversationId: string];
+}
+/**
+ * Main SDK class for managing voice conversations
+ */
+declare class AnganyVoice extends EventEmitter<VoiceEvents> {
+    private logger;
+    private config;
+    private conversations;
+    /**
+     * Authentication manager instance
+     */
+    readonly auth: AuthManager;
+    constructor(config: VoiceConfig);
+    /**
+     * Get the current configuration
+     */
+    getConfig(): VoiceConfig;
+    /**
+     * Start a new conversation
+     */
+    startConversation(resourceId: string, options?: Partial<ConversationOptions>): Promise<Conversation>;
+    /**
+     * Get an existing conversation by ID
+     */
+    getConversation(id: string): Conversation | undefined;
+    /**
+     * Get all active conversations
+     */
+    getConversations(): Conversation[];
+    /**
+     * End all conversations and cleanup
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * Error classes for the Angany Voice SDK
+ *
+ * Provides a hierarchy of error types for different failure scenarios.
+ * All SDK errors extend from AnganyError for easy error handling.
+ *
+ * @example Catching specific errors
+ * ```typescript
+ * try {
+ *   await voice.startConversation('agent');
+ * } catch (error) {
+ *   if (error instanceof AuthenticationError) {
+ *     // Handle auth failure
+ *   } else if (error instanceof NetworkError) {
+ *     // Handle network issue
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Base error class for all SDK errors
+ *
+ * All SDK-specific errors extend from this class, making it easy
+ * to catch any SDK error with a single catch block.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // SDK operations
+ * } catch (error) {
+ *   if (error instanceof AnganyError) {
+ *     console.log('SDK error:', error.code, error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class AnganyError extends Error {
+    /**
+     * Machine-readable error code
+     *
+     * Use this for programmatic error handling instead of parsing messages.
+     */
+    readonly code: string;
+    /**
+     * Additional error details
+     *
+     * May contain extra context, original errors, or debugging information.
+     */
+    readonly details?: any;
+    /**
+     * Timestamp when the error occurred
+     */
+    readonly timestamp: Date;
+    constructor(message: string, code: string, details?: any);
+    /**
+     * Get a JSON representation of the error
+     *
+     * Useful for logging or sending error reports.
+     *
+     * @returns JSON-serializable error object
+     */
+    toJSON(): Record<string, any>;
+}
+/**
+ * Authentication-related errors
+ *
+ * Thrown when authentication fails or tokens are invalid/expired.
+ *
+ * @example
+ * ```typescript
+ * throw new AuthenticationError('Invalid credentials', {
+ *   reason: 'wrong_password'
+ * });
+ * ```
+ */
+declare class AuthenticationError extends AnganyError {
+    constructor(message: string, details?: any);
+}
+/**
+ * Network-related errors
+ *
+ * Thrown when network requests fail or connections are lost.
+ *
+ * @example
+ * ```typescript
+ * throw new NetworkError('Connection timeout', {
+ *   url: 'https://api.angany.ai',
+ *   timeout: 30000
+ * });
+ * ```
+ */
+declare class NetworkError extends AnganyError {
+    constructor(message: string, details?: any);
+}
+/**
+ * Permission-related errors
+ *
+ * Thrown when required permissions are denied (e.g., microphone access).
+ *
+ * @example
+ * ```typescript
+ * throw new PermissionError('Microphone access denied', {
+ *   permission: 'microphone',
+ *   state: 'denied'
+ * });
+ * ```
+ */
+declare class PermissionError extends AnganyError {
+    constructor(message: string, details?: any);
+}
+/**
+ * Conversation-related errors
+ *
+ * Thrown when conversation operations fail.
+ *
+ * @example
+ * ```typescript
+ * throw new ConversationError('Failed to start conversation', {
+ *   resource: 'support-agent',
+ *   reason: 'resource_not_found'
+ * });
+ * ```
+ */
+declare class ConversationError extends AnganyError {
+    constructor(message: string, details?: any);
+}
+/**
+ * Configuration errors
+ *
+ * Thrown when SDK is misconfigured or required options are missing.
+ *
+ * @example
+ * ```typescript
+ * throw new ConfigurationError('Missing required option: apiUrl', {
+ *   option: 'apiUrl',
+ *   provided: config
+ * });
+ * ```
+ */
+declare class ConfigurationError extends AnganyError {
+    constructor(message: string, details?: any);
+}
+/**
+ * Resource errors
+ *
+ * Thrown when requested resources are not found or unavailable.
+ *
+ * @example
+ * ```typescript
+ * throw new ResourceError('Voice bot not found', {
+ *   resource: 'custom-agent',
+ *   availableResources: ['support', 'sales']
+ * });
+ * ```
+ */
+declare class ResourceError extends AnganyError {
+    constructor(message: string, details?: any);
+}
+/**
+ * Validation errors
+ *
+ * Thrown when input validation fails.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Invalid phone number format', {
+ *   field: 'phoneNumber',
+ *   value: '123',
+ *   pattern: /^\+?[1-9]\d{1,14}$/
+ * });
+ * ```
+ */
+declare class ValidationError extends AnganyError {
+    constructor(message: string, details?: any);
+}
+/**
+ * Media errors
+ *
+ * Thrown when audio/video operations fail.
+ *
+ * @example
+ * ```typescript
+ * throw new MediaError('Failed to acquire microphone', {
+ *   constraints: { audio: true },
+ *   browserError: error
+ * });
+ * ```
+ */
+declare class MediaError extends AnganyError {
+    constructor(message: string, details?: any);
+}
+/**
+ * Common error codes used throughout the SDK
+ *
+ * Use these constants for consistent error handling.
+ *
+ * @example
+ * ```typescript
+ * if (error.code === ErrorCodes.TOKEN_EXPIRED) {
+ *   await auth.refreshTokens();
+ * }
+ * ```
+ */
+declare const ErrorCodes: {
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    readonly TOKEN_INVALID: "TOKEN_INVALID";
+    readonly REFRESH_FAILED: "REFRESH_FAILED";
+    readonly LOGIN_REQUIRED: "LOGIN_REQUIRED";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly CONNECTION_LOST: "CONNECTION_LOST";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly SERVER_ERROR: "SERVER_ERROR";
+    readonly RESOURCE_NOT_FOUND: "RESOURCE_NOT_FOUND";
+    readonly RESOURCE_UNAVAILABLE: "RESOURCE_UNAVAILABLE";
+    readonly QUOTA_EXCEEDED: "QUOTA_EXCEEDED";
+    readonly MICROPHONE_DENIED: "MICROPHONE_DENIED";
+    readonly MICROPHONE_NOT_FOUND: "MICROPHONE_NOT_FOUND";
+    readonly MEDIA_ERROR: "MEDIA_ERROR";
+    readonly SIP_REGISTRATION_FAILED: "SIP_REGISTRATION_FAILED";
+    readonly CALL_FAILED: "CALL_FAILED";
+    readonly CONVERSATION_ENDED: "CONVERSATION_ENDED";
+    readonly INVALID_CONFIG: "INVALID_CONFIG";
+    readonly MISSING_REQUIRED_OPTION: "MISSING_REQUIRED_OPTION";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+    readonly NOT_IMPLEMENTED: "NOT_IMPLEMENTED";
+};
+/**
+ * Helper function to check if an error is an SDK error
+ *
+ * @param error - Error to check
+ * @returns True if the error is an AnganyError
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // SDK operation
+ * } catch (error) {
+ *   if (isAnganyError(error)) {
+ *     console.log('SDK error code:', error.code);
+ *   }
+ * }
+ * ```
+ */
+declare function isAnganyError(error: unknown): error is AnganyError;
+/**
+ * Helper function to check if an error is a specific type
+ *
+ * @param error - Error to check
+ * @param code - Error code to match
+ * @returns True if the error has the specified code
+ *
+ * @example
+ * ```typescript
+ * if (hasErrorCode(error, ErrorCodes.TOKEN_EXPIRED)) {
+ *   // Handle token expiration
+ * }
+ * ```
+ */
+declare function hasErrorCode(error: unknown, code: string): boolean;
+
+/**
+ * SDK version
+ * This is automatically updated during the release process
+ */
+declare const VERSION = "0.0.1";
+
+export { AnganyError, AnganyVoice, type AuthError, type AuthEvents, AuthManager, type AuthOptions, type AuthState, type AuthStatus, AuthenticationError, type BackendAuthOptions, type ClientCredentials, ConfigurationError, Conversation, ConversationError, type ConversationOptions, type ConversationState, type ConversationStatus, ErrorCodes, EventEmitter, type FrontendAuthOptions, type LogLevel, MediaError, NetworkError, PermissionError, ResourceError, type ServiceAccountAuthOptions, type ServiceAccountCredentials, type SpeakOptions, type TokenSet, type TranscriptionEvent, type UserInfo, VERSION, ValidationError, type VoiceConfig, type VoiceResource, hasErrorCode, isAnganyError };