@autonomoss/chat-react

Bindings React sobre o Autonomoss Web SDK. Duas formas de uso: o componente pronto <ChatAutonomoss /> (o que a maioria dos consumidores instala e usa em ~10 linhas) ou o hook headless useAutonomossChat, para quem quer construir a própria UI em React sem reimplementar sessão, streaming e atributos.

Instalação

Pacote público — instala normalmente, sem autenticação:

npm install @autonomoss/chat-react

Também publicado em espelho no GitHub Packages — útil se sua organização já centraliza dependências ali; requer um .npmrc com token read:packages (ver documentação do GitHub Packages).

Peer dependencies: react e react-dom ^18 || ^19 (já presentes em qualquer app React moderno — não são instaladas automaticamente).

Quickstart — <ChatAutonomoss />

import { ChatAutonomoss } from '@autonomoss/chat-react'

function App() {
  return (
    <ChatAutonomoss
      config={{
        publishableKey: 'pk_...',
        baseUrl: 'https://sua-api.exemplo.com/v1/embed',
        attributes: {
          secure: {
            access_token: { format: 'bearer_token', value: () => keycloak.token! },
          },
        },
      }}
      launcher={{ icon: 'chat', position: 'bottom-right' }}
    />
  )
}

Por baixo, monta o mesmo widget de @autonomoss/chat (Shadow DOM, tema AA, streaming, histórico, anexos e fullscreen já testados naquele pacote) dentro de um container gerido pelo React — não é uma reimplementação em JSX.

config/theme/launcher só são lidos na montagem inicial (mesmo padrão do Stripe Elements): trocar esses props depois não remonta nem reconfigura o widget. Para forçar uma sessão nova (ex.: troca de usuário logado), monte o componente com uma key diferente.

Props de <ChatAutonomoss />

| Prop | Tipo | Obrigatório | Descrição | | --------------------- | ---------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | config | AutonomossConfig | sim | publishableKey + attributes — ver README do @autonomoss/chat-core. | | theme | AutonomossChatTheme | não | Cores, título, avatar — ver README do @autonomoss/chat. | | launcher | { icon?: 'chat' \| 'support'; position?: 'bottom-right' \| 'bottom-left' } | não | Presente = bolha flutuante + painel; ausente = painel preenche o elemento (modo inline). | | openOnMount | boolean | não | Painel já aberto ao montar (ignorado em modo inline, que já é sempre "aberto"). | | showHistory | boolean | não | Botão de histórico de conversas no cabeçalho. Default: true. | | className / style | string / React.CSSProperties | não | Aplicados ao container que o widget monta dentro. | | onOpen / onClose | () => void | não | Disparados ao abrir/fechar o painel (modo flutuante). | | onMessage | (event: EmbedStreamEvent) => void | não | Todo evento do stream de chat, cru — ver tipos em @autonomoss/chat-core. | | onError | (event: { reason: string; message: string }) => void | não | Erro nomeado, já com mensagem amigável pt-BR. |

useAutonomossChat — UI própria

Para quem prefere construir sua própria interface (bolhas de mensagem, composer, etc.) em vez de usar o widget pronto:

import { useAutonomossChat } from '@autonomoss/chat-react'

function CustomChat() {
  const { messages, isStreaming, error, sendMessage } = useAutonomossChat({
    config: {
      publishableKey: 'pk_...',
      baseUrl: 'https://sua-api.exemplo.com/v1/embed',
      attributes: { secure: {} },
    },
  })

  return (
    <div>
      {messages.map((m) => (
        <p key={m.id} data-role={m.role} data-status={m.status}>
          {m.content}
        </p>
      ))}
      {error && <p role="alert">{error.message}</p>}
      <button disabled={isStreaming} onClick={() => sendMessage('Olá!')}>
        Enviar
      </button>
    </div>
  )
}

Sem Context/Provider: a instância de EmbedClient é criada uma única vez (via useRef) e vive presa ao componente, nunca recriada em re-renders.

Opções (UseAutonomossChatOptions)

Uma das duas formas:

{ config: AutonomossConfig; onEvent?: (event: EmbedStreamEvent) => void }
// ou, se você já gerencia o client em outro lugar (ex. compartilhado entre componentes):
{ client: EmbedClient; onEvent?: (event: EmbedStreamEvent) => void }

Quando você passa client (em vez de config), o hook não chama .destroy() nele ao desmontar — quem criou o client continua responsável pelo seu ciclo de vida.

Retorno (UseAutonomossChatResult)

| Campo | Tipo | Descrição | | ---------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | client | EmbedClient | Instância crua do @autonomoss/chat-core, para casos avançados (client.threads, client.connect(), etc.). | | messages | AutonomossChatMessage[] | { id, chatId, role: 'user' \| 'assistant', content, status: 'streaming' \| 'done' \| 'error' }. | | isStreaming | boolean | true enquanto uma resposta está sendo recebida. | | error | { reason: string; message: string } \| null | Último erro nomeado, com mensagem já pronta para exibir. | | sendMessage(text) | (text: string) => Promise<void> | Envia uma mensagem. Lança se chamado enquanto isStreaming já é true. | | setAttributes(patch) | (patch: { public?: Record<string, unknown> }) => void | Atualiza atributos públicos sem recriar a sessão. |

Erros

Erros não lançam para fora de sendMessage de forma silenciosa: a mensagem do assistente correspondente recebe status: 'error' no array messages, e o campo error do hook é populado com { reason, message } — a mesma forma normalizada e segura para exibir ao usuário que normalizeFriendlyError produz no core (ver cookbook de erros do @autonomoss/chat-core para a lista completa de reasons).

Segurança

A pk_ é pública e pode ficar no frontend. O SDK nunca pede sk_ e não usa localStorage nem cookies — sessão e atributos seguros vivem só em memória. Ver a seção Segurança do @autonomoss/chat-core para o detalhamento completo.

Versionamento

Este pacote segue Changesets — ver CHANGELOG.md.