@seedgrid/pulse-subscriber-react
v3.0.0
Published
SDK de referência (React + TypeScript) para assinar o SeedGrid Pulse: conecta no WebSocket, assina canais/grupos, recebe mensagens e envia ack. Protocolo realtime v1.
Maintainers
Readme
@seedgrid/pulse-subscriber-react
SDK de referência (React + TypeScript) para assinar o SeedGrid Pulse: conecta
no WebSocket, assina canais/grupos, recebe mensagens em tempo real, confirma
recebimento (ack) e reporta o resultado de execução (result, com DLQ/retry).
Implementa o contrato PulseSubscriber do PULSE_SDK_PLAN.md sobre o protocolo
realtime v1 (ver PROTOCOL.md).
Entrega dois níveis:
- Core framework-agnóstico —
PulseSubscriberClient(funciona em qualquer ambiente comWebSocket). - Camada React — hook
usePulseSubscriber+PulseProvideropcional.
O que é
Um cliente tipado que fala exatamente o protocolo do Pulse:
handshake (account key) → connected → subscribe → subscribed
↓
message → ack (recebido) → processa → result (execução)- autenticação somente no handshake (a identidade da conexão é o
account_idresolvido pela chave; o cliente nunca declarauserId); - reconexão automática (fixa ou exponencial, com jitter);
- replay de backlog ao reconectar (a assinatura é reenviada e o servidor reentrega o que ficou pendente);
ackexplícito e idempotente (confirma o RECEBIMENTO);reportResultpara reportar o RESULTADO DE EXECUÇÃO (success/retryable/permanent) — a única via que leva acompletedou à DLQ;- deduplicação opcional por
messageId(transactional inbox) para o at-least-once do Pulse; - callbacks de estado, incluindo erro de autenticação.
Quando usar
- app React (web) que precisa reagir a eventos do Pulse em tempo real;
- qualquer runtime JS/TS (Node, Deno, Electron, React Native) via o core — use
import { PulseSubscriberClient } from "@seedgrid/pulse-subscriber-react/core".
Quando NÃO usar
- para publicar mensagens: isso é papel do
PulsePublisher(server-side, usa a chaveprojectda conta). Este SDK só assina/consome. - para administrar contas/chaves: isso vive dentro do
pulse/pulse-ui. - não embarque nenhuma chave no browser: lá a conexão é com token curto (
getToken).
Instalação
npm install @seedgrid/pulse-subscriber-react
# peer deps (apenas para a camada React):
npm install react react-domDetalhes em INSTALLATION.md.
Quickstart (React)
import { usePulseSubscriber } from "@seedgrid/pulse-subscriber-react";
function Inbox() {
const { messages, connectionState, ack } = usePulseSubscriber({
// O token vem do SEU backend (que o pede ao Pulse para o usuário da sessão).
// Nenhuma chave no front.
getToken: async () => (await fetch("/api/realtime/connect", { method: "POST" })).json(),
subscription: { channels: ["orders"], groups: ["tenant:15"] },
autoAck: false,
});
return (
<div>
<span>status: {connectionState}</span>
<ul>
{messages.map((m) => (
<li key={m.messageId}>
{m.event}
{m.requiresAck && (
<button onClick={() => ack({ messageId: m.messageId })}>ack</button>
)}
</li>
))}
</ul>
</div>
);
}⚠️ Autenticação no browser: o servidor Pulse atual aceita a account key apenas via header
Authorization: Bearerno handshake — e oWebSocketnativo do navegador não envia headers. Em produção web, coloque um reverse-proxy same-origin que injeta esse header (recomendado), ou rode o core em um runtime que suporta headers (Nodews, React Native, Electron). Veja CONFIGURATION.md e SECURITY.md.
Conceitos centrais
| Conceito | Descrição |
|----------|-----------|
| account key | credencial da conexão. Resolve o account_id no handshake. NÃO é credencial de publicação. |
| channel | categoria funcional da mensagem (orders, finance, ...). |
| group | agrupamento lógico (tenant:15) para entrega por grupo. |
| ack | confirma o RECEBIMENTO de uma entrega (mensagem → delivered). |
| result | reporta o RESULTADO DE EXECUÇÃO (success/retryable/permanent); leva a completed ou à DLQ. |
| replay | reentrega de pendências ao (re)assinar após reconexão. |
| dedup | deduplicação por messageId (transactional inbox) contra o at-least-once. |
API pública (resumo)
Core — PulseSubscriberClient
// Opcional: liga a deduplicação por messageId (transactional inbox).
new PulseSubscriberClient({ processedStore: new InMemoryProcessedStore() });
connect(input: ConnectInput): Promise<void>;
subscribe(input: SubscribeInput): Promise<void>;
ack(input: AckInput): Promise<void>; // RECEBIMENTO
reportResult(messageId: string, result: ExecutionResult): Promise<void>; // EXECUÇÃO
disconnect(): Promise<void>;
onMessage(handler): Unsubscribe;
onStateChange(handler): Unsubscribe;
onError(handler): Unsubscribe; // frames {"type":"error"}
onAcknowledged(handler): Unsubscribe; // frames {"type":"acknowledged"}ExecutionResult é uma união discriminada:
type ExecutionResult =
| { outcome: "success" }
| { outcome: "retryable"; reason?: string; retryAfterSecs?: number }
| { outcome: "permanent"; reason: string };Frames result emitidos na rede:
{ "type": "result", "messageId": "msg_1", "outcome": "success" }
{ "type": "result", "messageId": "msg_1", "outcome": "retryable", "reason": "db down", "retryAfterSecs": 30 }
{ "type": "result", "messageId": "msg_1", "outcome": "permanent", "reason": "invalid payload" }React — usePulseSubscriber(options) retorna
{ messages, connectionState, connectionId, accountId, ack, reportResult, subscribe, connect, reconnect, disconnect, clearMessages, client }.
Ligue a dedup com a opção dedup: true (store em memória) ou dedup: <ProcessedStore>.
Deduplicação (transactional inbox)
A entrega do Pulse é at-least-once: uma mensagem pode ser reentregue se o
ack/result se perdeu ou após um replay de reconexão. Para aplicar o efeito de
negócio uma única vez, ative a dedup:
import {
PulseSubscriberClient,
InMemoryProcessedStore, // LRU em memória (efêmero)
LocalStorageProcessedStore, // persistente por origem no browser
type ProcessedStore, // implemente para IndexedDB/banco (inbox real)
} from "@seedgrid/pulse-subscriber-react/core";
const client = new PulseSubscriberClient({
processedStore: new InMemoryProcessedStore(),
});Com a dedup ligada: numa reentrega de um messageId já processado com sucesso, o
handler da aplicação é pulado e result: success é re-reportado
automaticamente; o id é registrado no store logo após um reportResult(..., {
outcome: "success" }). Idealmente o efeito de negócio e o registro do id ocorrem
na mesma transação persistente — para isso implemente ProcessedStore sobre seu
banco/IndexedDB.
Tipos completos em CONFIGURATION.md.
Matriz de compatibilidade
| Item | Suportado |
|------|-----------|
| Protocolo Pulse | v1 |
| React | 18+ (peer dependency) |
| Node | 18+ (via core + ws) |
| Módulos | ESM + CJS |
| Tipos | TypeScript (declarations incluídas) |
| SSR (Next.js/Remix) | sim — conexão só abre no cliente (useEffect) |
| Auth no browser | via reverse-proxy que injeta Authorization (ver docs) |
Mapa de documentação
- INSTALLATION.md — requisitos, instalação, CI.
- CONFIGURATION.md — todas as opções, autenticação, TLS, reconnect.
- FRONTEND_EXAMPLES.md — cenários reais de UI.
- SECURITY.md — modelo de credenciais e storage.
- TESTING.md — unit + integração com o harness.
- TROUBLESHOOTING.md — 401, loops, replay, CORS, TLS, clock skew.
- docs/diagrams/ — diagramas Mermaid.
- examples/ — app React de exemplo.
- CHANGELOG.md
Licença
MIT.
