gb-desk-widget

Widget de suporte do GB Desk no seu SaaS: o cliente abre chamado sem sair da tela em que está, e o atendente recebe junto a tela, o navegador e a versão em que o problema aconteceu.

npm i gb-desk-widget

import { Desk } from 'gb-desk-widget';

Desk.configure({ workspace: 'seu-slug' });

// depois do login, com o hash calculado no SEU backend
await Desk.identify({
  user:   { id: user.id, name: user.name, email: user.email },
  tenant: { id: clinic.id, name: clinic.name, plan: 'pro' },
  user_hash: hashDoBackend,
  context: { screen: 'Prescrição › Assinar', version: '4.12.3' },
});

Só isso. O lanchador aparece no canto e o resto é com a gente.

Este pacote não contém o widget

Ele tem 2 kB e faz uma coisa: injeta a tag que carrega o widget do nosso hosting, e devolve a API tipada atrás de promessas. Duas consequências, e é bom conhecer as duas antes de instalar:

A favor: a correção de um bug nosso chega ao seu sistema sozinha, em minutos, sem você publicar nada. Se o widget viesse empacotado aqui dentro, cada correção viraria um npm update e um deploy seu — no canal por onde os seus usuários relatam problemas, que é o pior lugar para depender do deploy de outra pessoa.

Contra: o navegador de quem usa o seu sistema faz uma requisição a um host nosso. Se você tem CSP, ele precisa estar liberado (veja abaixo). Se isso não for aceitável no seu caso — rede fechada, política de fornecedor —, fale com a gente: existe a versão com o bundle embutido.

Sem login (landing, site institucional)

Desk.configure({ workspace: 'seu-slug', anonimo: true });

Não precisa de identify, nem de backend, nem de segredo: o widget se identifica sozinho e pede nome, e-mail e WhatsApp antes da primeira tela — sem isso não haveria como responder quem fecha a aba. Exige o modo anônimo ligado no seu workspace, no painel do GB Desk.

user_hash

Sem ele, qualquer página poderia dizer que é outro usuário e ler as conversas dele. O segredo do workspace é entregue uma vez ao admin e fica só no seu backend:

// Node
const user_hash = require('node:crypto')
  .createHmac('sha256', process.env.GBDESK_SECRET)
  .update(String(user.id))
  .digest('hex');

A mensagem é String(user.id) — não o objeto user, não o e-mail —, o resultado é hex minúsculo, e o id do hash tem de ser o mesmo id que vai no identify(). Os três erros de sempre, todos com o mesmo sintoma: 401 invalid_user_hash.

API

| | | | --- | --- | | Desk.configure({ workspace, anonimo?, src?, endpoint? }) | Guarda a configuração. Não baixa nada. | | Desk.identify(payload) → Promise<IdentifyResponse> | Identifica e monta o widget. Única chamada obrigatória. | | Desk.open('home' \| 'new' \| 'conversations') · Desk.close() | Para pendurar num item de menu seu. | | Desk.setContext({ screen, version }) | Chame na troca de rota. Não fala com o servidor. | | Desk.on(evento, fn) → () => void | identified, conversation:created, conversation:rated, conversation:reopened. O cancelamento volta síncrono, para caber num useEffect. | | Desk.preload() | Adianta o download numa tela ociosa. Opcional. |

As funções também são exportadas soltas (import { identify, open } from 'gb-desk-widget').

// React: assinar e cancelar como manda o figurino
useEffect(() => Desk.on('conversation:created', ({ urgent }) => track('suporte', { urgent })), []);

// Vue Router / Next: mantenha a tela do atendente em dia
router.afterEach((rota) => Desk.setContext({ screen: rota.meta.titulo, version: APP_VERSION }));

SSR

Importar este pacote no servidor não quebra: nada toca o DOM no import, e a tag só nasce na primeira chamada. Se você chamar identify() durante a renderização no servidor, a promessa é recusada com uma mensagem que diz exatamente isso. Chame no cliente — useEffect, onMounted, if (typeof window !== 'undefined').

CSP

script-src   https://gb-desk-widget-867dd.web.app
connect-src  https://<seu-projeto>.supabase.co  wss://<seu-projeto>.supabase.co
img-src      https://<seu-projeto>.supabase.co
media-src    https://<seu-projeto>.supabase.co
style-src    https://fonts.googleapis.com 'unsafe-inline'
font-src     https://fonts.gstatic.com

'unsafe-inline' em style-src não é preguiça: o widget injeta o próprio CSS dentro do Shadow DOM e usa atributos style. Sem isso ele aparece sem estilo nenhum.

A origem do seu sistema precisa estar autorizada no workspace (Admin → Workspace → Origens permitidas), com esquema e porta. Fora da lista, o identify responde 403 origin_not_allowed — é o erro de instalação mais comum.

Requisitos

Navegadores com Shadow DOM (todos os atuais). Pacote ESM; bundlers modernos (Vite, webpack 5, Next.js, Nuxt) o entendem sem configuração.

Licença

MIT — e o que ela cobre é este pacote, a casca de 8 kB que carrega o widget. O widget em si continua servido pelo GB Desk, e o acesso a ele é o seu workspace e o seu segredo, não o código daqui.

Documentação completa da API e de tudo o que o widget faz pela rede: docs/API.md e docs/ROTAS.md.