@autonomoss/chat

Widget de chat pronto, agnóstico de framework, sobre @autonomoss/chat-core. Monta num Shadow DOM (não iframe) — tema com contraste AA, streaming incremental, histórico de conversas, anexos, passos de execução visíveis e fullscreen. Se você usa React, prefira @autonomoss/chat-react (<ChatAutonomoss />), que monta este mesmo widget por baixo.

Instalação

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

npm install @autonomoss/chat

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).

Sem dependência de framework — funciona em qualquer página HTML/JS.

Quickstart

import { mountAutonomossChat } from '@autonomoss/chat'

const widget = mountAutonomossChat('#chat-root', {
  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' },
})

target é um seletor CSS (string) ou um HTMLElement já resolvido. Sem launcher, o widget monta em modo inline (o painel preenche o próprio elemento, sempre aberto — útil para embutir num painel lateral fixo, por exemplo). Com launcher, monta em modo flutuante (bolha + painel, como um chat widget tradicional).

MountAutonomossChatOptions

| Campo | Tipo | Descrição | | ------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | config | AutonomossConfig | publishableKey + attributes — ver README do @autonomoss/chat-core. | | theme | AutonomossChatTheme | Ver Tema. | | launcher | { icon?: 'chat' \| 'support'; position?: 'bottom-right' \| 'bottom-left' } | Presente = flutuante; ausente = inline. | | openOnMount | boolean | Painel já aberto ao montar. Ignorado em modo inline (sempre "aberto"). Default: false. | | showHistory | boolean | Botão de histórico de conversas no cabeçalho. Default: true. |

AutonomossChatWidget (retorno de mountAutonomossChat)

| Membro | Descrição | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | open() / close() / toggle() | Controla o painel programaticamente (modo flutuante). | | isOpen() | Estado atual do painel. | | client | A instância de EmbedClient (@autonomoss/chat-core) por trás do widget — para casos avançados. | | setAttributes(patch) | Atualiza atributos públicos sem recriar a sessão. | | on(event, handler) / off(event, handler) | Eventos: open, close, message (todo EmbedStreamEvent), error. on retorna uma função de unsubscribe. | | destroy() | Remove o widget do DOM e libera os listeners. |

Tema

interface AutonomossChatTheme {
  title?: string
  backgroundColor?: string // hex, ex. '#0b1220'
  secondaryColor?: string // cor de destaque (launcher, bolha do assistente)
  fontColor?: string
  assistantAvatarUrl?: string | null
}

O contraste texto/fundo é recalculado automaticamente para atender AA (WCAG): se fontColor não atingir 4.5:1 de contraste contra backgroundColor, o widget escolhe branco ou quase-preto (o que der mais contraste) em vez do valor configurado — você nunca precisa calcular isso manualmente, mas também não deve assumir que fontColor sempre "vence".

assistantAvatarUrl só é aceito em HTTPS — URLs http://, javascript:, data: etc. são silenciosamente ignoradas e o widget cai para um avatar com a inicial do title.

i18n

Hoje o widget tem só um catálogo de strings, em pt-BR, sem mecanismo de troca de idioma. Se seu produto precisa de outro idioma, isso ainda não é suportado por este pacote — trate como uma limitação conhecida, não configure nada esperando efeito.

Isolamento de estilo

O widget monta num Shadow DOM (attachShadow({ mode: 'open' })), não num <iframe>: isolamento de CSS real (nada do host vaza pra dentro, nada do widget vaza pra fora) sem o custo de um documento HTML separado. Estilos são CSS-in-JS (template string), aplicados via adoptedStyleSheets quando disponível, com fallback para uma tag <style> dentro do próprio shadow root em browsers mais antigos ou ambientes sem suporte. Não é seguro sobrescrever esses estilos de fora (o Shadow DOM bloqueia isso por design) — use as opções de theme para personalizar cores/título/avatar.

Segurança

• Todo conteúdo interpolado no HTML do widget (título, avatar) passa por escaping — não é possível injetar HTML/JS via configuração de tema.
• Avatar remoto só é aceito em HTTPS (ver Tema).
• A pk_ é pública e pode ficar no frontend. O SDK nunca pede sk_ e não usa localStorage nem cookies. Ver a seção Segurança do @autonomoss/chat-core para o detalhamento completo.

Anexos

Até 3 arquivos por mensagem, 2 MB cada, allowlist de MIME (application/pdf, .docx, image/{png,jpeg,webp,gif}, text/plain) — processados em memória, nunca persistidos pelo widget.

Exemplo sem framework

Veja examples/widget para uma página HTML/TS pura montando este pacote.

Versionamento

Este pacote segue Changesets — ver CHANGELOG.md.