# @chattoo-br/browser

SDK TypeScript para React, Vite e Next.js. Sem dependências de runtime e sem módulos Node no navegador. Use `@chattoo-br/node` no servidor; o token do projeto permanece lá.

```sh
npm install @chattoo-br/browser
# Backend do gateway:
# npm install @chattoo-br/node
```

```tsx
'use client'; // Necessário no componente Next.js que usa eventos ou ações.
import {useEffect} from 'react';
import {ChattooBrowser} from '@chattoo-br/browser';
const chattoo = new ChattooBrowser(); // Gateway padrão: /api/chattoo
export function Example() {
  useEffect(() => chattoo.events.subscribe(event => {
    if (event.type === 'message.received') console.log(event.type);
  }), []); // O retorno fecha o stream ao desmontar.
  return <button onClick={() => chattoo.messages.sendText(
    {to: '+5511999999999', text: 'Olá!'},
    {idempotencyKey: 'confirmacao-pedido-123'},
  )}>Enviar</button>;
}
```

O número é fictício. Para cada nova intenção de negócio use uma chave nova; em repetição da mesma solicitação preserve a original. Uma falha de rede não dispara outro envio automaticamente. HTTP 202 é aceite; entrega e leitura vêm por eventos. O SDK não realiza pareamento, confirmação adicional por código ou gerenciamento de webhooks no navegador.

## Gateway Node

```ts
import {Chattoo, createNodeGatewayHandler, ChattooEventHub, createWebhookHandler} from '@chattoo-br/node';
const client = new Chattoo(process.env.CHATTOO_TOKEN!);
const hub = new ChattooEventHub();
const gateway = createNodeGatewayHandler({
  origin: 'https://seu-aplicativo.example',
  operations: ['messages.sendText', 'commands.get', 'sessions.get', 'events'],
  authorize: async request => {
    const user = await authenticateYourAppSession(request); // Sua autenticação.
    if (!user) return null;
    return {client, csrfToken: user.csrf, instanceId: user.allowedInstanceId, projectId: user.allowedProjectId};
  },
  events: (request, context) => hub.response(context.projectId!, request.signal, context.instanceId),
});
const webhook = createWebhookHandler({
  secret: process.env.CHATTOO_WEBHOOK_SECRET!,
  onEvent: event => hub.publish(event),
});
// No seu servidor HTTP, encaminhe /api/chattoo/* ao gateway e a URL de callback ao webhook.
```

As funções `authenticateYourAppSession` e as políticas de acesso pertencem ao aplicativo cliente. `authorize` é obrigatório. Apenas operações explicitamente habilitadas são expostas. Na POC, o usuário autorizado e sua instância são fixos, a sessão é HttpOnly e o stream fecha ao sair ou expirar.

O gateway confere origem, CSRF, instância e chave de idempotência; o SDK busca o CSRF automaticamente usando a sessão do aplicativo. Ao trocar de usuário sem recarregar a página, chame `resetSession()` para limpar o contexto anterior. Não há Bearer de projeto no código cliente, `VITE_*`, `NEXT_PUBLIC_*`, URL ou localStorage.

No arquivo `app/api/chattoo/[...path]/route.ts` do Next.js, use `createChattooGateway` com a mesma configuração: `export const GET = gateway; export const POST = gateway; export const runtime = 'nodejs';`. `authorize` continua obrigatório. Instanciar `ChattooBrowser` é compatível com SSR; assine eventos em `useEffect`, com o cancelamento retornado. O stream é SSE autenticado no mesmo domínio, reconecta automaticamente e entrega eventos `chattoo`.

## Recursos

- `instances.list/get`, `messages.sendText/sendTemplate`, `commands.get/list`, `sessions.get`.
- `events.subscribe(onEvent, {onOpen, onError})` retorna uma função que fecha o stream.
- `RequestOptions`: `idempotencyKey`, `signal`, `timeoutMs` (15 segundos por padrão).
- `ChattooBrowserError`: `code`, `status`, `requestId`; não contém token nem corpo da mensagem.

A disponibilidade depende da lista de operações e autorização do gateway do seu aplicativo. O hub Node mantém até 100 metadados por projeto, para até 100 projetos, e remove conteúdo/remetente do replay. Texto é entregue somente ao vivo. O armazenamento é limitado à memória do processo e não é um histórico de conversas. Réplicas exigem um transporte compartilhado fornecido pelo aplicativo. Webhook e vínculo WhatsApp não dependem de navegador aberto; visualização de texto ao vivo depende.

[POC para validação](https://apis.chattoo.com.br:8443/sdk-test/) · [Guia e Swagger](https://app.chattoo.com.br/developers)