# Sofya Transcription SDK

Browser SDK that captures audio and delivers it to a Sofya STT server, in real time or as a single upload, and returns the transcription.

## Language

### Connection

**Direct mode**:
A connection where the integrator gives the SDK the provider and the STT endpoint.
_Avoid_: endpoint mode, manual mode

**Discovery mode**:
A connection where the integrator gives only an api-key and the SDK asks the reasoner which provider and endpoint to use.
_Avoid_: apiKey mode (clashes with the **Api-key** credential)

**Stream session**:
A transcription session whose audio travels over a WebSocket while it is captured.
_Avoid_: realtime session, WS mode

**Batch session**:
A transcription session whose audio is sent to the STT in a single HTTP request.
_Avoid_: primary batch, upload mode

**Primary channel**:
The connection that carries the session's audio: the WebSocket in a **Stream session**, the HTTP POST in a **Batch session**.

**Auxiliary call**:
Any HTTP request the SDK makes to Sofya beyond the **Primary channel** (batch reprocess, audit ingestion).

**Final upload**:
The session's full audio, posted at stop to an endpoint the integrator owns.
_Avoid_: backup, archive upload

### Authentication

**Api-key**:
The credential that identifies the integrating client to the STT.
_Avoid_: token, key (unqualified)

**JWT**:
The integrator's own user credential, which the SDK forwards without interpreting or validating.
_Avoid_: token (also names the **Api-key** and subprotocol entries), bearer

**Auth strategy**:
The one credential a **Direct mode** session authenticates with: **Api-key** or **JWT**.
_Avoid_: auth mode, auth type

**Key transport**:
How the **Api-key** reaches the STT on the WebSocket: subprotocol or query.

**Companion subprotocol**:
The subprotocol the server echoes back when the **Api-key** travels as a subprotocol; the integrator's first protocol, or `sofya-stt.v1` when there is none.

## Relationships

- The SDK delivers the **Api-key** to the STT only in **Direct mode**; in **Discovery mode** it goes to the reasoner alone
- A session has exactly one **Auth strategy**; the **Primary channel** and every **Auxiliary call** follow it
- A **Key transport** applies only to the WebSocket
- A **Final upload** carries no credential; it is not an **Auxiliary call** and ignores the **Auth strategy**
- A **Stream session** has exactly one WebSocket **Primary channel** and zero or more **Auxiliary calls**
- An **Api-key** sent as a subprotocol always needs a **Companion subprotocol**
- STT authentication is optional per client: a **JWT** session reaches only STTs that do not require an **Api-key**

## Example dialogue

> **Dev:** "The integrator picked the query **Key transport** for a **Stream session** with batch reprocess on. Does the reprocess POST put the key in the URL too?"
> **Domain expert:** "No. The **Key transport** only covers the WebSocket. The reprocess is an **Auxiliary call**, so it follows the **Auth strategy**: the **Api-key** goes as a header."

## Flagged ambiguities

- "apiKey" named both the **Discovery mode** connection and the **Api-key** credential used in **Direct mode**. Resolved: these are distinct concepts.
- "token" named the **JWT**, the **Api-key** and subprotocol entries. Resolved: say **JWT** for the user credential.