@noorden/webchat

Widget de webchat da Noorden Platform — bundle vanilla leve (≈4 KB gzip), zero dependências de framework, CSS isolado em shadow DOM (nem o CSS do seu site quebra o widget, nem o widget vaza estilo).

Fala com os endpoints públicos do canal webchat da plataforma (/v1/webchat/:connectionId/...). Crie a conexão webchat no console (loja de integrações → Webchat) e configure as origens permitidas — sem elas o widget não abre em nenhum site.

Instalação via snippet (2 linhas)

<script src="https://unpkg.com/@noorden/[email protected]/dist/cdn/embed.js"></script>
<script>
  Noorden.init({ baseUrl: 'https://SUA-API', connectionId: 'conn_...' });
</script>

Instalação via bundler

npm install @noorden/webchat

import { init } from '@noorden/webchat';

const chat = init({
  baseUrl: 'https://SUA-API',
  connectionId: 'conn_...',
  title: 'Fale conosco',
  primaryColor: '#4f46e5',
  position: 'right', // ou 'left'
});

chat.open(); // abre o painel programaticamente
chat.close();
chat.destroy(); // desmonta o widget e fecha o stream

Contrato público (0.1.0, semver)

init(config): WebchatHandle

| opção | tipo | default | descrição | | -------------- | ------------------------- | ------------------------- | ---------------------------------------------------------- | | baseUrl | string (obrigatório) | — | Base pública da API, sem barra final | | connectionId | string (obrigatório) | — | Conexão webchat (conn_…) criada no console | | title | string | "Fale conosco" | Título do painel + aria-label da bolha | | primaryColor | string | #4f46e5 | Cor da bolha/header/botão | | position | 'left' \| 'right' | 'right' | Canto da tela | | placeholder | string | "Escreva uma mensagem…" | Placeholder do composer | | identity | { userId, name?, hmac } | — | Identidade verificada (HMAC calculado no seu servidor) | | zIndex | number | 2147483000 | z-index do container |

Handle: open(), close(), destroy().

Comportamento

• Visitante anônimo: o visitorId devolvido no handshake fica no localStorage (nrdwc:<connectionId>:vid) — reabre a mesma conversa no reload.
• Identidade verificada (padrão Intercom): passe identity com hmac = HMAC-SHA256(identitySecret, "webchat-identity:" + userId) calculado no seu backend. Nunca exponha o identitySecret no browser.
• Tempo real: respostas chegam por SSE (GET /stream); replay é deduplicado por id. O histórico local (cap de 200 mensagens) fica no localStorage, por conexão e por sujeito.
• Token: o visitorToken é renovado automaticamente (handshake) antes de expirar e em 401.
• Erros: falha de conexão/envio vira estado visível no widget (nunca exceção solta).
• Acessibilidade: bolha com aria-expanded, painel role="dialog", thread aria-live="polite", Escape fecha e devolve o foco.

Segurança

• Mensagens são inseridas via textContent — markup do interlocutor nunca vira DOM.
• O widget só carrega em origens permitidas pela conexão (allowlist checada no servidor).
• Identidade anônima é, por definição, fraca; use identidade verificada para usuários logados.