bug-report-client

Widget de feedback in-app, agnóstico a framework, para reportar bugs e sugerir melhorias com contexto visual e técnico.

O botão de report pode ficar oculto e aparecer só quando o usuário parece estar com problemas (request com erro, clique sem resposta, erros repetidos…). O report chega ao seu backend com captura da tela, os sinais do problema e os últimos passos do usuário.

Documentação

| Documento | Descrição | |-----------|-----------| | Índice | Visão geral e navegação | | Integração | React, Vue, Angular, vanilla JS, headless e migração 1.x → 2.0 | | Referência da API | Tipos, classes e configuração | | Backend | Contrato REST, idempotência, deduplicação, rate limit | | Segurança | PII, armazenamento local, CSP e políticas de acesso | | Arquitetura | Módulos e fluxos | | Desenvolvimento | Build, testes, demonstração e publicação | | Changelog | Mudanças por versão |

Recursos

• Botão sob demanda (visibility: 'on-friction'): aparece ao detectar erro JS, request com erro ou lento, clique sem resposta, rage click, formulário recusado, vai e volta entre páginas, página de erro ou erros repetidos (também entre páginas da mesma aba)
• Jornada do usuário anexada ao report: páginas, cliques, requests e sinais, sem dados pessoais
• Captura fiel à tela do elemento ou da área visível, com campos e [data-sensitive] ocultados
• Marcações: destacar o problema ou ocultar áreas; opção de enviar sem imagem
• Fila offline: sem conexão, o report é guardado e reenviado com a mesma chave de idempotência
• Idiomas pt-BR, en e es, com textos sobrescrevíveis
• Acessível: seleção de elemento por teclado, foco gerenciado, anúncios para leitores de tela
• Isolado: UI em Shadow DOM, compatível com CSP estrito
• Métricas: onReveal, onConceal, onFlowStart, onDismiss, onQueued
• Adapters de erro para Angular, React e Vue, sem dependência de framework
• API headless e tipos TypeScript

Instalação

npm install bug-report-client

html-to-image já vem como dependência. Requer ambiente com DOM (browser).

Início rápido

import { createBugReportWidget } from 'bug-report-client';

const widget = createBugReportWidget({
  productId: 'my-app',
  apiUrl: 'https://api.example.com',
  environment: 'prod',
  appVersion: '1.0.0',
  visibility: 'on-friction', // ou 'always' (padrão)
  onSuccess: (reportId) => console.log('Enviado:', reportId),
  onError: (error) => showToast(error.message), // só falha no POST /feedback/reports
});

widget.mount();

// Erros de negócio que não geram exceção:
widget.reportFriction({ message: 'Pagamento recusado', signature: 'payment-declined' });

Experimente sem backend: npm run demo e abra http://127.0.0.1:4789/demo/.

Fluxo

1. O usuário clica no botão (sempre visível ou revelado por detecção de problema).
2. Seleciona um elemento com mouse ou teclado, ou envia feedback sem selecionar. ESC cancela.
3. No modal, escolhe Problema ou Sugestão, descreve, revisa a captura, pode marcar/ocultar áreas ou enviar sem imagem.
4. O pacote envia POST {apiUrl}/feedback/reports (multipart). Sem conexão, guarda e reenvia depois.

Configuração principal

| Campo | Obrigatório | Descrição | |-------|:-----------:|-----------| | productId, apiUrl, environment, appVersion | sim | Identificação do produto e da API | | visibility | não | always (padrão) ou on-friction | | friction | não | Limiar, pesos, sinais, revealLabel, cooldownMs, persistência entre páginas | | journey | não | Histórico de passos (padrão ligado); false desliga | | locale / messages | não | Idioma (pt-BR, en, es, auto) e sobrescrita de textos | | allowAnnotation / allowScreenshotOptOut | não | Marcações e envio sem imagem (padrão ligados) | | offlineQueue | não | Fila offline (padrão ligada) | | accentColor, fabLabel | não | Aparência | | authMode, authProvider, captchaProvider | não | Autenticação e captcha | | stepProvider, disableOnSteps, enabled | não | Onde o widget fica disponível | | metadataProviders | não | Metadados extras (sanitizados) | | excludeSelectors | não | Áreas fora da captura e do seletor | | styleNonce | não | Nonce do CSP (só em browsers sem constructable stylesheets) | | onSuccess, onError, onQueued, onReveal, onConceal, onFlowStart, onDismiss | não | Callbacks |

Lista completa na Referência da API.

Frameworks

// Angular: erros do framework viram sinais de problema
providers: [{ provide: ErrorHandler, useFactory: () => createAngularErrorHandler(() => inject(BugReportService).widget) }];

// React
const BugReportErrorBoundary = createReactErrorBoundary(React, () => widget);

// Vue 3
app.config.errorHandler = createVueErrorHandler(widget);

Exemplos completos no guia de integração.

Backend

POST {apiUrl}/feedback/reports com multipart/form-data: type, description, productId, environment, metadata (JSON), idempotencyKey e, opcionalmente, screenshot (PNG) e captchaToken. Resposta: { "id", "status", "createdAt" }.

Reenvios usam a mesma idempotencyKey: crie um índice único em (productId, idempotencyKey). Detalhes em docs/backend.md.

Desenvolvimento

npm install
npm run typecheck && npm run test:unit && npm run test:e2e

Ver docs/desenvolvimento.md e PUBLISHING.md.

Licença

MIT — Macelo Melo