@omnizapi/connect 1.0.0

package/README.md

@@ -0,0 +1,195 @@
+# @omnizapi/connect
+
+SDK Omnizapi para conectar canais Meta WhatsApp, Messenger, Instagram, Telegram e Z-API WhatsApp em aplicacoes web. Coleta o resultado da autorizacao; seu backend valida e finaliza a conexao. Nao envie secret keys ao frontend.
+
+## Instalacao e importacao
+
+```bash
+npm install @omnizapi/connect
+```
+
+```ts
+import Omnizapi, { Environment, OmnizapiError } from "@omnizapi/connect";
+// Alternativa: import { Omnizapi } from "@omnizapi/connect";
+import type {
+  OmnizapiClient,
+  OmnizapiClientProps,
+  ConnectionOptions,
+  ConnectionResult,
+  ConnectionSuccess,
+  ConnectionFailure,
+  ConnectionFailureReason,
+  OmnizapiErrorCode,
+  ChannelType,
+} from "@omnizapi/connect";
+```
+
+CommonJS: `const { Omnizapi } = require("@omnizapi/connect")`.
+
+No navegador, o bundle expoe o global `Omnizapi`:
+
+```html
+<script src="https://unpkg.com/@omnizapi/connect/dist/omnizapi.min.js"></script>
+```
+
+Fixe uma versao publicada e homologada no CDN antes do deploy. Imports ESM/CommonJS e `newClient` sao seguros em SSR; `connect` exige navegador e rejeita com `BROWSER_REQUIRED` no servidor. O bundle de script e exclusivo do navegador.
+
+## Uso
+
+```ts
+const client = Omnizapi.newClient({ publicKey: "sua-public-key" });
+```
+
+Dispare `client.connect({ channelId })` em um clique, nunca durante renderizacao, montagem ou importacao. Os exemplos completos incluem UI, `try/catch/finally`, tratamento de `reason` e envio ao backend:
+
+| Exemplo | Uso |
+| --- | --- |
+| [TypeScript basico](examples/basic.ts) | Botao e mensagem de status no DOM |
+| [HTML com CDN](examples/vanilla.html) | Pagina sem bundler |
+| [React / Next.js](examples/react.tsx) | `'use client'`, cliente por componente via `useState` lazy |
+| [Angular](examples/angular.ts) | Componente com guarda de navegador para SSR |
+| [Vue](examples/vue.vue) | SFC com guarda de navegador para SSR |
+| [Opcoes](examples/with-options.ts) | SANDBOX, URLs explicitas, logo, fluxo padrao/direto e timeout |
+| [Erros](examples/error-handling.ts) | Mensagens para todos os motivos e codigos tipados |
+
+Os exemplos usam `/api/connect-channel` como rota **da sua aplicacao**, nao fornecida por este pacote. Ela deve autenticar a sessao, validar o resultado e responder com HTTP 2xx somente quando a finalizacao tiver sido confirmada. Os exemplos aguardam `fetch` e verificam `response.ok` antes de exibir sucesso. Adapte a autenticacao e a protecao CSRF ao seu backend. Nao registre resultados, tokens, codigos OAuth ou erros brutos que possam conter URLs sensiveis.
+
+## API
+
+### `Omnizapi.newClient(props): OmnizapiClient`
+
+`OmnizapiClientProps`:
+
+| Campo | Tipo | Descricao |
+| --- | --- | --- |
+| `publicKey` | `string` | Obrigatorio; chave publica Omnizapi |
+| `logo` | `string` | URL opcional da logo no popup proxy |
+| `environment` | `Environment` | Padrao `Environment.PRODUCTION` |
+| `apiUrl` | `string` | Sobrescreve a URL base da API |
+| `frontUrl` | `string` | Sobrescreve a URL base do frontend de conexao |
+
+| Ambiente | API padrao | Frontend padrao |
+| --- | --- | --- |
+| `PRODUCTION` | `https://api.omni.z-api.io` | `https://app.omni.z-api.io` |
+| `STAGING` | `https://api.staging.omni.z-api.io` | `https://app.staging.omni.z-api.io` |
+| `SANDBOX` | Exige URL configurada | Exige URL configurada |
+
+Precedencia por URL: **props > `OMNIZAPI_API_URL` / `OMNIZAPI_FRONT_URL` no build do SDK > padroes do ambiente**. Variaveis do processo da aplicacao nao reconfiguram um bundle ja compilado; para isso use props. SANDBOX exige ambas as URLs, via props ou build. URLs base devem ser HTTP(S), sem credenciais, query ou fragmento; use HTTPS em producao. Configuracao invalida pode lancar `OmnizapiError` com `INVALID_CONFIGURATION` na criacao do cliente.
+
+### `client.connect(options): Promise<ConnectionResult>`
+
+`ConnectionOptions`:
+
+| Campo | Tipo | Descricao |
+| --- | --- | --- |
+| `channelId` | `string` | Obrigatorio; canal a conectar |
+| `direct` | `boolean` | Solicita Meta WhatsApp Embedded Signup sem o popup proxy; nao se aplica aos outros canais. O SDK tambem escolhe o fluxo nativo com `appCustom` ou na origem do frontend de conexao |
+| `getQRCode` | `() => Promise<{ connected?: boolean; value?: string }>` | Callback opcional para integracao QR com o frontend externo; veja os limites abaixo |
+| `timeoutMs` | `number` | Prazo total positivo e finito em ms, ate `2147483647`; padrao **600000 (10 minutos)** |
+
+HTTP e carregamento do SDK Facebook tem limite de **30 segundos**, respeitando o prazo total restante da tentativa. O POST ao seu backend nao faz parte desse prazo e precisa de politica propria de timeout.
+
+Ha **uma tentativa ativa por pagina**, inclusive entre clientes diferentes. Outra chamada concorrente rejeita com `CONNECTION_IN_PROGRESS`; nao implemente retry automatico para abrir popups. Mesmo a partir de um clique, um popup aberto depois de um `await` pode ser bloqueado: trate `POPUP_BLOCKED` e permita nova tentativa pelo usuario.
+
+O retorno e uma uniao discriminada por `success`, nao uma confirmacao de persistencia no seu backend:
+
+| Tipo | Campos |
+| --- | --- |
+| `ConnectionSuccess` | `success: true`, `channelId: string`, `type: ChannelType`, `coexistence: boolean`; `code`, `wabaId`, `phoneId`, `redirectUri`, `botToken`, `pageId`, `accessToken`: `string \| null` |
+| `ConnectionFailure` | `success: false`, `reason: ConnectionFailureReason`, `channelId: string`, `type: ChannelType \| null`; `code`, `wabaId`, `phoneId`: `null` |
+
+`ChannelType`: `META_MESSENGER`, `META_INSTAGRAM`, `META_WHATSAPP`, `BOT_TELEGRAM`, `Z_API_WHATSAPP`. Nem todos os canais retornam as mesmas credenciais. O resultado de sucesso inclui `channelId`: envie-o junto ao backend e confira sua vinculacao a sessao/tenant no servidor.
+
+Resultados negativos resolvem a Promise e nao significam sempre cancelamento:
+
+| `reason` | Significado |
+| --- | --- |
+| `cancelled` | Fluxo cancelado |
+| `popup_closed` | Popup fechado antes da conclusao |
+| `not_completed` | Fluxo nao concluido |
+| `invalid_channel` | ID de canal vazio ou canal rejeitado pelo fluxo |
+| `origin_not_allowed` | Origem da aplicacao nao autorizada para o canal |
+| `unsupported_channel` | Tipo de canal nao suportado |
+
+Falhas tecnicas rejeitam com `OmnizapiError`; use `instanceof OmnizapiError` e `error.code`, nao o texto da mensagem:
+
+| Codigo | Significado |
+| --- | --- |
+| `BROWSER_REQUIRED` | Operacao exige navegador |
+| `CONNECTION_IN_PROGRESS` | Tentativa ativa nesta pagina ou login Meta nativo anterior incompleto; veja os limites abaixo |
+| `INVALID_CONFIGURATION` | Props ou configuracao de ambiente invalidas |
+| `INVALID_OPTIONS` | Opcoes da operacao invalidas, como `channelId` com tipo incorreto ou timeout invalido |
+| `NETWORK_ERROR` | Falha de transporte |
+| `HTTP_ERROR` | Resposta HTTP sem sucesso |
+| `INVALID_RESPONSE` | Resposta da API invalida |
+| `POPUP_BLOCKED` | Navegador impediu a abertura do popup |
+| `TIMEOUT` | Prazo de operacao excedido |
+| `SDK_LOAD_FAILED` | Falha ao carregar/inicializar SDK do provedor |
+| `PROVIDER_ERROR` | Erro reportado pelo provedor |
+
+### `client.getListMessengerPages(channelId, code): Promise<unknown>`
+
+Consulta as paginas Messenger usando o codigo OAuth e o canal. Valide o retorno antes de acessa-lo: o schema externo ainda nao foi confirmado, portanto o SDK nao publica DTO de pagina. Nao use cast para inventar esse contrato, nem registre o codigo ou a resposta. A chamada tambem pode rejeitar com erro tecnico e tem timeout HTTP de 30 segundos.
+
+## Protocolo de popup
+
+Este contrato exige deploy coordenado do frontend/proxy e backend externos; nenhum desses servicos e alterado neste repositorio. Nao ha fallback para mensagens sem os identificadores exigidos.
+
+1. O SDK gera `attemptId` por tentativa. Popups abertos diretamente no `frontUrl` recebem `attemptId` na query. No OAuth Messenger/Instagram, o `state` JSON e `{ currentUrl, attemptId, channelId }`; o proxy deve preserva-lo e vincula-lo a sessao autorizada, ao canal e ao tenant. `state` e query nao sao prova de autorizacao por si so.
+2. A pagina final deve estar na origem exata de `frontUrl` e emitir da **propria janela popup** aberta pelo SDK, nao de iframe, outra janela ou backend. Ela responde ao `window.opener` usando `postMessage` com `type: 'after-connect'`, `attemptId`, `channelId`, `success` e as credenciais aplicaveis. `attemptId` e `channelId` devem corresponder exatamente a tentativa ativa.
+3. O SDK verifica a origem exata do frontend, `event.source` igual ao popup ativo e os dois identificadores. O emissor usa `targetOrigin` igual a origem exata da aplicacao autorizada, nunca wildcard e nunca uma origem derivada de query/state nao validados.
+4. Sucesso dos proxies Meta exige `code`; Telegram exige `botToken`. `Z_API_WHATSAPP` pode retornar sucesso autenticado sem credenciais, mas o backend deve confirmar a conexao real para aquele canal/tenant. Para negativo, envie `success: false` e o `reason` tipado aplicavel, sem credenciais.
+
+Mensagens com origem, janela, identificadores ou formato incorretos sao ignoradas; a tentativa continua aguardando conclusao, fechamento ou timeout. Uma mensagem de sucesso sem a credencial exigida resulta em `not_completed`.
+
+Trecho ilustrativo **no frontend externo**, apos o servidor validar a sessao e a autorizacao da tentativa. `authorizedSession` representa dados validados pelo servidor, nao um DTO deste SDK; nao a construa lendo parametros da URL sem validacao:
+
+```js
+const { applicationOrigin, attemptId, channelId } = authorizedSession;
+// applicationOrigin e uma origem exata previamente autorizada para esta sessao.
+// code foi validado para o fluxo Meta desta mesma tentativa.
+if (window.opener) {
+  window.opener.postMessage(
+    { type: "after-connect", attemptId, channelId, success: true, code },
+    applicationOrigin,
+  );
+}
+```
+
+O Meta Embedded Signup **nativo** nao fornece `attemptId` nem uma referencia customizada da janela emissora (`event.source`) para correlacao. Ele usa a allowlist exata `https://www.facebook.com` / `https://web.facebook.com` e o callback `FB.login`. Nao se pode garantir o isolamento de eventos nativos tardios entre tentativas; essas verificacoes nao sao garantia absoluta de seguranca.
+
+Se um login nativo for iniciado e nao terminar com sucesso, novas tentativas nativas exigem **recarregar a pagina** (`CONNECTION_IN_PROGRESS`), mesmo apos cancelamento, erro ou timeout e sem outra tentativa ativa. Essa restricao evita reutilizar uma sessao nativa incompleta; nao se aplica aos popups proxy.
+
+Durante uma tentativa, apenas `__omnizapiPublicKey`, `__omnizapiCurrentChannel` e `__omnizapiGetQrCode` sao publicados temporariamente para o frontend externo. Uma funcao QR no `window` da aplicacao nao atravessa origens nem e serializada por `postMessage`: o frontend precisa de uma integracao explicitamente autorizada e compativel com a politica de mesma origem. Este repositorio nao valida por si so o fluxo Z-API real nem confirma essa integracao externa.
+
+## App da Meta proprio (`appCustom`)
+
+Por padrao o canal usa o app da Meta da plataforma, e a Meta so enxerga o `frontUrl` (`app.hubmessage.io` ou `app.omni.z-api.io`): o login do WhatsApp e o retorno do OAuth do Messenger e do Instagram acontecem na janela da plataforma. Nesse caso o seu dominio nao precisa de nada na Meta, so na allowlist de origens do canal.
+
+Quando o canal tem app proprio (`appCustom` no `sdk-info`), o SDK muda de comportamento: o login do WhatsApp Meta (Embedded Signup) roda **na sua propria pagina**, com o seu `appId` e `configId`, e o OAuth do Messenger e do Instagram continua voltando para a plataforma. Entao o **seu** app da Meta precisa conhecer os dois lados:
+
+| Onde no app da Meta | O que cadastrar |
+| --- | --- |
+| Facebook Login > Configuracoes > Dominios permitidos para o SDK do JavaScript | Todas as origens onde o seu site chama `connect` (ex.: `https://www.suaempresa.com.br`), e o `frontUrl` da plataforma se voce tambem conecta pelo painel |
+| Facebook Login > Configuracoes > URIs de redirecionamento do OAuth validos | `${frontUrl}/oauth/proxy-messenger` e `${frontUrl}/oauth/proxy-instagram` da marca que voce usa (ex.: `https://app.omni.z-api.io/oauth/proxy-messenger`) |
+| Configuracoes basicas > Dominios do app | O dominio do seu site e o da plataforma |
+| WhatsApp > Embedded Signup | A configuracao cujo id e o `configId` cadastrado na plataforma; o app precisa ter os produtos WhatsApp, Messenger e Instagram habilitados conforme os canais que vai conectar |
+
+Sem o dominio do seu site nos dominios do SDK, a Meta recusa o `FB.login` com erro de dominio e o SDK rejeita com `PROVIDER_ERROR`. Sem os redirects, o OAuth do Messenger e do Instagram para na tela da Meta com "URL bloqueada". Sem a origem do seu site na allowlist do canal, o SDK resolve com `origin_not_allowed` antes de abrir qualquer janela.
+
+## Checklist de deploy
+
+- [ ] Publicar `@omnizapi/connect` com exports default/named `Omnizapi`, tipos atualizados e `dist/omnizapi.min.js`; atualizar imports, script tags e configuracao dos consumidores em conjunto.
+- [ ] Configurar `OMNIZAPI_API_URL` / `OMNIZAPI_FRONT_URL` no build ou `apiUrl` / `frontUrl` nas props; conferir producao, staging e ambas as URLs de sandbox.
+- [ ] Manter na API as rotas existentes `GET /instances/:channelId/sdk-info` e `POST /v1/channels/:channelId/list-messenger-pages`, com autenticacao por chave publica, schema validado e sem exposicao de secrets.
+- [ ] Manter no frontend `/oauth/proxy-cloud-api`, `/oauth/proxy-messenger`, `/oauth/proxy-instagram`, `/connect/telegram` e `/connect/whatsapp-web`, inclusive ao usar uma URL base com prefixo.
+- [ ] Conferir a logo customizada e o asset padrao `${frontUrl}/logos/SVG/Ativo%2016.svg`, acessiveis por HTTPS e com identidade Omnizapi.
+- [ ] Autorizar as origens exatas da aplicacao por canal e configurar CORS da API para essas origens, metodos e headers (`Authorization`, `Content-Type`). Validacao client-side nao substitui autorizacao no servidor.
+- [ ] Cadastrar os redirects Meta exatos `${frontUrl}/oauth/proxy-messenger` e `${frontUrl}/oauth/proxy-instagram`, alem de dominios/configuracoes do Embedded Signup e app IDs corretos.
+- [ ] Implementar preservacao de `state`, sessao autorizada e protocolo `after-connect` acima em todas as rotas; confirmar origem final, janela emissora, `attemptId`, `channelId` e `targetOrigin` exatos. Conferir politicas de navegador/COOP que possam remover `opener`.
+- [ ] Validar no backend sessao, CSRF, canal/tenant e credenciais especificas do provedor antes de finalizar; trocar/armazenar tokens somente no servidor, limitar repeticao/replay e nao aceitar `success: true` do navegador como prova suficiente.
+- [ ] Homologar cancelamento, fechamento/bloqueio de popup, concorrencia, timeout, mensagens de origem/janela/tentativa incorretas e falhas HTTP; validar em servicos reais a integracao QR e cada canal, inclusive Z-API. Os exemplos nao substituem essa homologacao.
+
+## Licenca
+
+MIT - FourPixel IT. Autor: FourPixel IT.