Conexões

Tipos de Conexão

O SDK suporta diferentes modos de conexão baseados no provedor:

Conexão com Chave de API

{
  apiKey: string;
  config?: BaseConfig;
}

Conexão com Provedor Sofya Compliance

{
  provider: "sofya_compliance";
  endpoint: string;
  config: SofyaComplianceConfig;
}

Conexão com Provedor Sofya As Service

{
  provider: "sofya_as_service";
  endpoint: string;
  config: SofyaSpeechConfig;
}

Tipos de Configuração

BaseConfig

interface BaseConfig {
  language: string;
  external_id?: string;
  record?: boolean;
}

Campo	Tipo	Descrição
external_id	string (opcional)	Identificador da consulta na sua aplicação. Enviado ao servidor como query param x-external-id em toda conexão — reconexões incluídas — e usado para agrupar as gravações da mesma consulta. Opaco: UUID, hash, id interno; nunca CPF, nome, prontuário legível ou e-mail. Para ser usado literalmente no caminho da gravação: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ (letra ou dígito no início, até 64, sem : / espaço acento); fora disso o servidor usa um hash no caminho e guarda o original só nos metadados. Até 512 caracteres. Use o mesmo valor em toda reconexão.
record	boolean (opcional)	Pede (true) ou recusa (false) a gravação desta sessão no servidor. Omitido, o padrão do ambiente decide — o SDK não envia nada. true só grava se o ambiente permitir; caso contrário a sessão segue normalmente. Gravar nunca altera a transcrição.

const transcriber = new SofyaTranscriber({
  provider: "sofya_as_service",
  endpoint: "<wss-url>",
  config: {
    language: "pt-BR",
    external_id: "<id-da-consulta>",
    record: true,
  },
});

Compatibilidade

external_id e record são aditivos e opcionais. Aplicações que não os usem continuam funcionando exatamente como antes, inclusive contra servidores antigos.

SofyaComplianceConfig

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

SofyaSpeechConfig

interface SofyaSpeechConfig extends BaseConfig {
  auth?: DirectModeAuth;
}

Autenticação no Modo Direto (auth)

Conexões diretas ({ provider, endpoint, config }) podem enviar a chave de API do STT pelo campo opcional config.auth. Ele existe nas configs dos provedores Whisper diretos (sofya_as_service, sofya_whisper_flow, stt_wvad); a conexão por chave de API continua igual, porque já se autentica pela API Sofya.

type DirectModeAuth =
  | { type: "none" }
  | {
      type: "api_key";
      key: string;
      transport?: "subprotocol" | "query";
    }
  | { type: "jwt"; token: string };

Campo	Tipo	Descrição
type	"none" | "api_key" | "jwt"	"none" é o padrão quando auth é omitido e não envia credencial. "api_key" envia a chave de API do STT. "jwt" envia um JWT no lugar dela (veja JWT).
key	string	A chave de API do STT. Obrigatória quando type é "api_key". O SDK nunca transforma o valor.
transport	"subprotocol" | "query" (opcional)	Como a chave chega ao servidor. Padrão "subprotocol". O navegador não define cabeçalhos no handshake do WebSocket, então essas são as duas únicas opções.
token	string	O JWT puro. Obrigatório quando type é "jwt". Sem Bearer : o SDK adiciona o prefixo.

transport: "subprotocol" (padrão)

A chave viaja como um token extra de Sec-WebSocket-Protocol, x-api-key.<chave>. O servidor remove esse token antes da aplicação vê-lo e devolve o primeiro subprotocolo solicitado, então o SDK mantém os seus protocolos na frente e acrescenta o token da chave por último.

const transcriber = new SofyaTranscriber({
  provider: "sofya_as_service",
  endpoint: "<wss-url>",
  config: {
    language: "pt-BR",
    auth: { type: "api_key", key: "<chave-api-stt>" },
  },
});

config.protocols	Subprotocolos enviados no handshake
omitido	["sofya-stt.v1", "x-api-key.<chave>"]
"bearer.jwt"	["bearer.jwt", "x-api-key.<chave>"]
["bearer.jwt", "sofya-stt.v1"]	["bearer.jwt", "sofya-stt.v1", "x-api-key.<chave>"]

• O servidor recusa o handshake em que o token da chave é o único subprotocolo (subprotocol_companion_required); por isso o SDK acrescenta o token acompanhante sofya-stt.v1 quando você não configura nenhum protocolo.
• Tokens de subprotocolo do RFC 6455 aceitam apenas letras, dígitos e !#$%&'*+-.^_`|~ — =, /, ,, espaços e aspas não são permitidos. Com uma chave fora desse conjunto o SDK lança SofyaAuthError antes de conectar; emita uma chave compatível ou use o transporte query.

transport: "query"

A chave é anexada à URL de tempo real como o parâmetro x-api-key e os config.protocols seguem intactos.

const transcriber = new SofyaTranscriber({
  provider: "sofya_as_service",
  endpoint: "<wss-url>",
  config: {
    language: "pt-BR",
    auth: {
      type: "api_key",
      key: "<chave-api-stt>",
      transport: "query",
    },
  },
});

Chaves em URLs

URLs são registradas por proxies, gateways, logs de acesso e histórico do navegador. Prefira subprotocol e use query só quando a chave não puder ser um token RFC 6455.

• As reconexões reutilizam a mesma autenticação — a URL e a lista de subprotocolos são remontadas igualmente a cada tentativa.
• A chave também vai como cabeçalho x-api-key nas chamadas HTTP feitas pelo SDK (reprocessamento em lote e ingestão de auditoria), a menos que esse cabeçalho já esteja configurado.
• O SDK nunca registra a chave em log: ela aparece como [redacted] na saída de debug.
• Quando o servidor recusa a chave, ele nega o handshake com HTTP 401 ou fecha com o código 4401. No 4401 o SDK emite error com um SofyaAuthError (código AUTH_REJECTED) e para de reconectar, em vez de repetir a mesma chave.

Compatibilidade

auth é aditivo e opcional. Omiti-lo (ou usar { type: "none" }) mantém o comportamento anterior, inclusive os protocols configurados e a URL.

type: "jwt"

Envia um JWT no lugar da chave de API. As duas estratégias são exclusivas: a sessão se autentica com uma delas, e toda requisição do SDK segue a escolhida.

const transcriber = new SofyaTranscriber({
  provider: "sofya_as_service",
  endpoint: "<wss-url>",
  config: {
    language: "pt-BR",
    auth: { type: "jwt", token: "<jwt>" }, // "eyJ...", não "Bearer eyJ..."
  },
});

Informe o JWT puro

Não adicione Bearer ao token: o SDK adiciona o prefixo nas requisições HTTP. Um token que começa com Bearer faz o SDK lançar SofyaAuthError com o código INVALID_JWT antes de conectar; o prefixo nunca é removido em silêncio.

Requisição	api_key	jwt
WebSocket	subprotocolo x-api-key.<chave> (último) ou query x-api-key	o JWT como primeiro subprotocolo, antes de config.protocols, e o servidor o ecoa
Batch, batch reprocess, audit ingestion	cabeçalho x-api-key	Authorization: Bearer <token>
Final upload	nada	nada

• Sessões realtime enviam o JWT como subprotocolo, então ele precisa ser um token RFC 6455. Um JWT padrão (base64url, sem padding) sempre é; qualquer coisa com =, /, ,, espaços ou aspas lança SofyaAuthError (INVALID_JWT_CHARACTERS) antes de conectar. Sessões batch enviam o JWT só no cabeçalho e aceitam qualquer caractere.
• Não coloque o JWT também em config.protocols, senão ele vai duas vezes.
• Um cabeçalho Authorization definido em config.headers vence o JWT.
• O STT da Sofya não valida JWT. Use jwt com STTs que têm a autenticação desligada ou ficam atrás de um gateway que valida o token; um STT que exige chave de API recusa a conexão. O audit ingestion exige x-api-key, então só com jwt ele é pulado com o aviso missing_api_key.
• O JWT nunca aparece na saída de debug ([redacted]).

config.token obsoleto

No modo direto, config.token está obsoleto e será removido na 1.0.0; use auth: { type: "jwt", token }. Até lá ele continua virando Authorization: Bearer <token>, o SDK registra um aviso de descontinuação, e auth.token vence quando os dois são informados.

Fluxo de Conexão

Fluxo de Conexão com Chave de API

1. O SDK autentica com a API Sofya usando a chave de API fornecida.
2. A API retorna uma lista de provedores disponíveis e suas configurações.
3. O SDK tenta conectar a cada provedor em ordem até que uma conexão bem-sucedida seja estabelecida.
4. Uma vez conectado, o SDK emite um evento 'ready'.

Fluxo de Conexão Específico do Provedor

1. O SDK tenta conectar diretamente ao provedor especificado usando o endpoint e configuração fornecidos.
2. Uma vez conectado, o SDK emite um evento 'ready'.