# Connection Mode Documentation

This document provides detailed information about the connection modes supported by the Sofya Transcription SDK.

## Overview

The Sofya Transcription SDK supports multiple connection modes to accommodate different providers and authentication methods. The connection mode is specified when creating a new instance of the `SofyaTranscriber` class.

## Connection Types

### API Key Connection

The API key connection mode is used when you want to authenticate with the Sofya API using an API key. This mode allows the SDK to automatically discover and connect to available providers.

```typescript
const transcriber = new SofyaTranscriber({
  apiKey: 'YOUR_API_KEY',
  config: {
    language: 'en-US'
  }
});
```

#### Properties

- `apiKey` (string, required): Your Sofya API key.
- `config` (BaseConfig, optional): Base configuration for the transcription service.

### Provider-Specific Connections

Provider-specific connections are used when you want to connect directly to a specific provider without using the Sofya API. This mode requires you to provide the provider-specific configuration and endpoint.

#### Sofya Compliance Provider

```typescript
const transcriber = new SofyaTranscriber({
  provider: 'sofya_compliance',
  endpoint: 'YOUR_ENDPOINT',
  config: {
    language: 'en-US',
    token: 'YOUR_TOKEN',
    compartmentId: 'YOUR_COMPARTMENT_ID',
    region: 'YOUR_REGION'
  }
});
```

#### Sofya As Service Provider

```typescript
const transcriber = new SofyaTranscriber({
  provider: 'sofya_as_service',
  endpoint: 'YOUR_ENDPOINT',
  config: {
    language: 'en-US'
  }
});
```

#### STT WVAD Provider

```typescript
const transcriber = new SofyaTranscriber({
  provider: 'stt_wvad',
  endpoint: 'YOUR_ENDPOINT',
  config: {
    language: 'en-US'
  }
});
```

## Configuration Types

### BaseConfig

The `BaseConfig` interface defines the common configuration properties shared by all providers.

```typescript
interface BaseConfig {
  language: string;
}
```

#### Properties

- `language` (string, required): The language code for transcription (e.g., 'en-US', 'pt-BR').

### SofyaComplianceConfig

The `SofyaComplianceConfig` interface extends `BaseConfig` and adds Sofya Compliance-specific configuration properties.

```typescript
interface SofyaComplianceConfig extends BaseConfig {
  token: string;
  compartmentId: string;
  region: string;
}
```

#### Properties

- `language` (string, required): The language code for transcription (e.g., 'en-US', 'pt-BR').
- `token` (string, required): The authentication token.
- `compartmentId` (string, required): The compartment ID.
- `region` (string, required): The region (e.g., 'us-ashburn-1').

### SofyaSpeechConfig

The `SofyaSpeechConfig` interface extends `BaseConfig` and can be extended with Sofya As Service-specific configuration properties.

```typescript
interface SofyaSpeechConfig extends BaseConfig {
  // Additional Sofya As Service-specific config properties can be added here
}
```

#### Properties

- `language` (string, required): The language code for transcription (e.g., 'en-US', 'pt-BR').

## Connection Flow

### API Key Connection Flow

1. The SDK authenticates with the Sofya API using the provided API key.
2. The API returns a list of available providers and their configurations.
3. The SDK attempts to connect to each provider in order until a successful connection is established.
4. Once connected, the SDK emits a 'ready' event.

### Provider-Specific Connection Flow

1. The SDK attempts to connect directly to the specified provider using the provided endpoint and configuration.
2. Once connected, the SDK emits a 'ready' event.

## Error Handling

The SDK provides comprehensive error handling for connection issues:

- If the API key is invalid or missing, the SDK will throw an error.
- If no providers are available for the API key, the SDK will throw an error.
- If the connection to a provider fails, the SDK will attempt to connect to the next provider.
- If all providers fail to connect, the SDK will throw an error.

## Events

The SDK emits the following events during the connection process:

- `ready`: Emitted when the transcription service is ready to start.
- `error`: Emitted when an error occurs during the connection process.
- `connected`: Emitted when the transcription service is connected to the provider.
- `recognizing`: Emitted when transcription is in progress.
- `recognized`: Emitted when transcription is complete.
- `stopped`: Emitted when the transcription process is stopped.

## Examples

### API Key Connection

```typescript
import { SofyaTranscriber } from 'sofya.transcription';

// Create a transcriber with API key connection
const transcriber = new SofyaTranscriber({
  apiKey: 'YOUR_API_KEY',
  config: {
    language: 'en-US'
  }
});

// Listen for ready event
transcriber.on('ready', () => {
  console.log('Transcription service is ready');
  
  // Get media stream and start transcription
  navigator.mediaDevices.getUserMedia({ audio: true })
    .then(mediaStream => {
      transcriber.startTranscription(mediaStream);
    })
    .catch(error => {
      console.error('Error accessing microphone:', error);
    });
});

// Listen for error event
transcriber.on('error', (error) => {
  console.error('Transcription error:', error);
});
```

### Sofya Compliance Provider Connection

```typescript
import { SofyaTranscriber } from 'sofya.transcription';

// Create a transcriber with Sofya Compliance provider connection
const transcriber = new SofyaTranscriber({
  provider: 'sofya_compliance',
  endpoint: 'YOUR_ENDPOINT',
  config: {
    language: 'en-US',
    token: 'YOUR_TOKEN',
    compartmentId: 'YOUR_COMPARTMENT_ID',
    region: 'YOUR_REGION'
  }
});

// Listen for ready event
transcriber.on('ready', () => {
  console.log('Transcription service is ready');
  
  // Get media stream and start transcription
  navigator.mediaDevices.getUserMedia({ audio: true })
    .then(mediaStream => {
      transcriber.startTranscription(mediaStream);
    })
    .catch(error => {
      console.error('Error accessing microphone:', error);
    });
});

// Listen for error event
transcriber.on('error', (error) => {
  console.error('Transcription error:', error);
});
```