Arquitetura

Os três pacotes, a fronteira de confiança e o caminho do áudio.

Arquitetura de pacotes

Três bibliotecas publicadas no npm sob @callixbrasil. Um pacote é uma biblioteca que o desenvolvedor instala com um comando e passa a usar no próprio código. A divisão não é arbitrária: cada um roda num lugar diferente, e é isso que mantém a chave de API fora do browser.

@callixbrasil/server-sdk

Roda no servidor do parceiro. Faz uma coisa só: troca a chave de API por um token de sessão de um usuário. É o único pedaço que conhece o segredo. Superfície mínima — uma classe, um método.

@callixbrasil/client-sdk

Roda no browser do agente. O núcleo. Registra o softphone (SIP/WebRTC), mantém a máquina de estados do operador, expõe a chamada atual, as pausas e as qualificações. Não depende de framework.

@callixbrasil/client-sdk-react

Camada opcional, para quem usa React. Empacota o núcleo em 17 hooks e um provider. É conveniência: quem não usa React fala direto com o núcleo, que expõe o mesmo estado por assinatura.

React não é obrigatório. O pacote client-sdk exporta a classe CallixClientSdk e os signals de estado (.get() e .subscribe()), o que permite consumo a partir de Angular, Vue, Svelte ou JavaScript puro. A ressalva: documentação e exemplos oficiais cobrem React, então esse é o caminho mais curto.

Arquitetura de integração

Quatro atores e uma linha que a chave de API nunca cruza. O áudio não passa pelo servidor do parceiro — vai direto do browser do agente para a plataforma.

O áudio vai direto do browser do agente para a plataforma — nunca passa pelo backend do parceiro.

O passo 3 é a razão de existir do server-sdk: o browser recebe um token de sessão descartável, nunca a chave de API. Quem obtiver o token consegue operar como aquele agente; quem obtivesse a chave de API operaria como qualquer um.

Obrigações que isso impõe à aplicação parceira

Ter um backend. Não há integração segura apenas com HTML e JavaScript no browser — algum servidor precisa guardar a chave de API.
Servir a aplicação por HTTPS. O browser não libera o microfone fora de contexto seguro (localhost é a exceção, para desenvolvimento).
Mapear usuário da aplicação → usuário da Callix. O token é emitido para um login específico da plataforma.