@omnizapi/connect 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [1.0.2] - 2026-09-10
+
+Primeira versao documentada neste changelog; nao reconstitui o historico de releases anteriores.
+
+### API e ciclo de vida
+
+- `ConnectionOptions.signal?: AbortSignal` permite interromper `connect` com `OmnizapiError.code === "ABORTED"` e limpeza dos recursos da tentativa, sem expor `signal.reason`. Nao desfaz autorizacoes no provedor nem operacoes ja recebidas pelo backend.
+- Uma tentativa ativa por pagina, inclusive entre clientes; reserva de popup `about:blank` no gesto e navegacao da mesma janela apos validar a configuracao. A selecao de fluxo nativo por `appCustom` fecha a janela provisoria; o gesto exigido pelo SDK Meta ainda depende de homologacao externa.
+- Quarentena nativa preservada quando o login termina sem callback Meta, inclusive por timeout ou abort. Callback de cancelamento ou tardio libera somente a tentativa dona, sem exigir reload para todo cancelamento.
+- Inicializacao rastreada pelo SDK Facebook reutilizada para o mesmo `appId` numerico, sem reinicializar silenciosamente o SDK do host; conflitos de app e inicializacao preexistente desconhecida degradam para o fluxo proxy na janela reservada (abaixo).
+- Chamadas externas ao `FB.init` observado invalidam o app conhecido, inclusive entre versoes da biblioteca. Timeouts inconclusivos de scripts externos impedem atribuir proveniencia propria a um carregamento tardio; recursos do host nao sao removidos.
+- `getListMessengerPages` permanece `Promise<unknown>`: o schema do servico externo nao foi confirmado. Os tipos publicos continuam importados da raiz de `@omnizapi/connect`. A chamada agora aceita um `AbortSignal` opcional como terceiro argumento; aborts rejeitam com `ABORTED` (antes `NETWORK_ERROR`) e sinais invalidos com `INVALID_OPTIONS`.
+- Conflito de app Meta ou SDK Meta do host com inicializacao desconhecida nao rejeita mais com `INVALID_CONFIGURATION`: a tentativa degrada para o fluxo proxy na janela reservada. A quarentena de login nativo (`CONNECTION_IN_PROGRESS`) nao degrada. Para canais `appCustom`, o fallback exige o dominio/redirects da plataforma cadastrados no app do cliente.
+- Um `FB.login` que lanca excecao sincrona libera imediatamente a quarentena nativa (nenhum dialogo abriu, nenhum callback chegara), permitindo nova tentativa sem recarregar a pagina.
+- A janela `about:blank` passa a ser reservada no clique para todos os canais, inclusive com `direct: true`: `direct` deixa de impedir a reserva e apenas solicita o fluxo nativo no WhatsApp Meta, corrigindo o `POPUP_BLOCKED` de `direct` em outros canais. Fechar a janela reservada antes da navegacao nao cancela a tentativa; `popup_closed` so ocorre quando o fluxo ja depende da janela.
+- A comparacao de `allowOrigins` normaliza cada entrada com `new URL(origin).origin`, aceitando entradas com barra final, path ou porta padrao.
+- As URLs de `/connect/telegram` e `/connect/whatsapp-web` incluem `pk` (a chave publica), permitindo ao frontend de conexao restringir o `targetOrigin` da resposta as origens autorizadas do canal em vez de `*`.
+
+### Exemplos e documentacao
+
+- Criacao/cache de clientes movidos para o `try` do clique nos exemplos TypeScript, React, Angular e Vue, permitindo exibir erros de configuracao sem falhar na importacao/renderizacao.
+- Exemplo de erros com mensagens tipadas exaustivas, inclusive `ABORTED`, e cancelamento controlado apenas durante a autorizacao. React usa `useRef` e cleanup com `AbortController`, sem atualizacoes apos desmontagem nem memoizacao desnecessaria.
+- Mensagens de retry ajustadas para nao exigir reload indiscriminado nem recomendar repetir uma finalizacao cujo estado no backend e desconhecido. Nenhum exemplo registra tokens ou erros brutos.
+- Scripts CDN e links UNPKG do README e do exemplo vanilla fixados na versao do manifesto; os exemplos locais sao os mesmos incluidos no pacote.
+- Documentacao de `appCustom` preservada e ampliada com limites de inicializacao compartilhada e de gesto nativo; `PROVIDER_ERROR` nao e prometido para toda recusa de dominio pela Meta.
+- Nota explicita de privacidade: `state.currentUrl` permanece a URL completa, inclusive query e fragmento, com risco de exposicao de tokens/dados sensiveis. Reduzir a origem depende de verificacao dos proxies e nao foi implementado nesta rodada.
+- Licenca MIT completa adicionada com copyright 2026 FourPixel IT, preservando a autoria.
+
+### Verificacao e release
+
+- Fluxo de desenvolvimento documentado com Node.js 22 via `.nvmrc`, `npm ci` e `npm run check` para lint, unitarios, build limpo e smoke tests.
+- Protecao de `pack`/`publish` via `prepack` e verificacao de defaults de producao Omnizapi, sem URLs customizadas embutidas no artefato de release. `npm run build` continua aceitando variaveis customizadas explicitas.
+- Testes de navegador documentados para Chromium, Firefox e WebKit, com preparacao previa dos binarios Playwright; CI de verificacoes sem publicacao automatica. Testes simulados nao substituem integracao com Meta/proxies reais.
+- Sincronizacao dos links versionados por `scripts/sync-version.mjs` em futuras alteracoes aprovadas com `npm version <nova-versao> --no-git-tag-version`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FourPixel IT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+Versao atual: **1.0.2**. As mudancas desta versao estao no [changelog](https://unpkg.com/browse/@omnizapi/connect@1.0.2/CHANGELOG.md), disponivel com o pacote publicado.
+
 ## Instalacao e importacao
 
 ```bash
@@ -29,28 +31,30 @@ 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>
+<script src="https://unpkg.com/@omnizapi/connect@1.0.2/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.
+O CDN usa uma versao fixa; homologue sua integracao 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" });
-```
+Crie/reutilize o cliente com `Omnizapi.newClient({ publicKey: "sua-public-key" })` dentro do `try` do handler de clique, para que `INVALID_CONFIGURATION` tambem seja tratado pela UI.
 
-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:
+Dispare `client.connect({ channelId })` diretamente no clique, sem outro `await` antes, 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 |
+| [TypeScript basico](https://unpkg.com/browse/@omnizapi/connect@1.0.2/examples/basic.ts) | Botao e mensagem de status no DOM |
+| [HTML com CDN](https://unpkg.com/browse/@omnizapi/connect@1.0.2/examples/vanilla.html) | Pagina sem bundler |
+| [React / Next.js](https://unpkg.com/browse/@omnizapi/connect@1.0.2/examples/react.tsx) | `'use client'`, UI de conexao por componente |
+| [Angular](https://unpkg.com/browse/@omnizapi/connect@1.0.2/examples/angular.ts) | Componente com guarda de navegador para SSR |
+| [Vue](https://unpkg.com/browse/@omnizapi/connect@1.0.2/examples/vue.vue) | SFC com guarda de navegador para SSR |
+| [Opcoes](https://unpkg.com/browse/@omnizapi/connect@1.0.2/examples/with-options.ts) | SANDBOX, URLs explicitas, logo, fluxo padrao/direto e timeout |
+| [Erros](https://unpkg.com/browse/@omnizapi/connect@1.0.2/examples/error-handling.ts) | Mensagens para todos os motivos e codigos tipados |
+
+Os links abrem o codigo-fonte dos exemplos da versao 1.0.2, incluido no pacote npm. Nao sao demos hospedadas: adapte as chaves, o canal e o backend na sua aplicacao.
+
+Os arquivos `examples/error-handling.ts` e `examples/react.tsx` demonstram `AbortSignal`. No React, o cliente fica em `useRef`, e so e criado no `try` do clique; o cleanup de `useEffect` aborta a tentativa/requisicao pendente sem atualizar a UI desmontada. O exemplo de erros usa `Record<OmnizapiErrorCode, string>` exaustivo e permite cancelar apenas a autorizacao, nao a finalizacao no backend. Nao ha botao para limpar a quarentena nativa.
 
 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.
 
@@ -83,13 +87,20 @@ Precedencia por URL: **props > `OMNIZAPI_API_URL` / `OMNIZAPI_FRONT_URL` no buil
 | 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 |
+| `direct` | `boolean` | Solicita Meta WhatsApp Embedded Signup sem o popup proxy; nao se aplica aos outros canais, que sempre usam a janela reservada. O SDK tambem escolhe o fluxo nativo com `appCustom` ou na origem do frontend de conexao, e degrada para o proxy quando a pagina nao pode rodar o nativo |
 | `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)** |
+| `signal` | `AbortSignal` | Opcional; permite interromper a tentativa via `AbortController` |
 
 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.
+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.
+
+O SDK reserva um popup `about:blank` durante o clique, para qualquer canal (com `direct` ou sem), antes de aguardar a configuracao do canal; apos validar a resposta, navega a mesma janela. A janela provisoria e fechada ao encerrar a tentativa ou ao iniciar o fluxo nativo, inclusive quando `appCustom` seleciona o nativo sem `direct`. Fechar a janela reservada antes da navegacao nao cancela a tentativa: o fechamento so resulta em `popup_closed` quando o fluxo ja depende da janela (apos a navegacao) ou quando ela e encontrada fechada na hora de navegar. Ainda trate `POPUP_BLOCKED` e permita nova tentativa por clique. A reserva nao transfere o gesto ao `FB.login`: o fluxo nativo, apos carregar a configuracao/SDK Meta, ainda exige homologacao externa com navegadores reais.
+
+**Cancelamento:** passe um sinal novo por tentativa. Se o sinal ja estiver abortado ou for abortado enquanto `connect` estiver pendente, a Promise rejeita com `OmnizapiError.code === "ABORTED"`, nao resolve com `reason: "cancelled"`. O SDK encerra requisicoes pendentes, timers e listeners da tentativa, fecha o popup que controla e restaura seus globais temporarios sem sobrescrever alteracoes do host, nem expor `signal.reason`. Scripts/callbacks de terceiros nao sao removidos; a observacao de um script Meta externo compartilhado pode continuar ate carregar, falhar ou atingir o limite de 30 segundos.
+
+Abort nao desfaz uma autorizacao na Meta, nao fecha necessariamente o dialogo nativo e nao remove a quarentena de um login nativo ainda sem callback. Depois que `connect` termina, abortar esse sinal nao cancela automaticamente seu POST; o React passa o sinal tambem ao `fetch`, mas nem isso desfaz operacoes ja recebidas pelo servidor. Confira o estado no backend antes de repetir uma finalizacao sem confirmacao.
 
 O retorno e uma uniao discriminada por `success`, nao uma confirmacao de persistencia no seu backend:
 
@@ -111,35 +122,40 @@ Resultados negativos resolvem a Promise e nao significam sempre cancelamento:
 | `origin_not_allowed` | Origem da aplicacao nao autorizada para o canal |
 | `unsupported_channel` | Tipo de canal nao suportado |
 
+Uma pagina servida com `Cross-Origin-Opener-Policy: same-origin` faz o navegador cortar a referencia da janela popup; o SDK reporta `popup_closed` (ou `POPUP_BLOCKED`), indistinguivel de um fechamento pelo usuario. Nao ha como diferenciar os dois casos via JavaScript: permita nova tentativa por clique e, se possivel, ajuste a politica da pagina de conexao.
+
 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 |
+| `INVALID_CONFIGURATION` | Props, ambiente ou APIs de navegador invalidos; conflitos de app/inicializacao do SDK Meta degradam para o fluxo proxy, sem rejeitar |
+| `INVALID_OPTIONS` | Opcoes da operacao invalidas, como `channelId` com tipo incorreto, timeout ou sinal 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 |
+| `ABORTED` | Tentativa interrompida pelo `AbortSignal` da aplicacao, com mensagem segura |
 | `SDK_LOAD_FAILED` | Falha ao carregar/inicializar SDK do provedor |
 | `PROVIDER_ERROR` | Erro reportado pelo provedor |
 
-### `client.getListMessengerPages(channelId, code): Promise<unknown>`
+### `client.getListMessengerPages(channelId, code, signal?): 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.
+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. O terceiro argumento aceita um `AbortSignal` opcional; um sinal abortado (antes ou durante a chamada) rejeita com `OmnizapiError.code === "ABORTED"`, e um sinal invalido rejeita com `INVALID_OPTIONS`.
 
 ## 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.
+1. O SDK gera `attemptId` por tentativa. Popups abertos diretamente no `frontUrl` recebem `attemptId` na query; as rotas `/connect/telegram` e `/connect/whatsapp-web` tambem recebem `pk` (a chave publica) na query, permitindo ao frontend consultar as origens autorizadas do canal e restringir o `targetOrigin` da resposta. 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.
 
+**Privacidade de `state`: `currentUrl` continua sendo `window.location.href` COMPLETO, incluindo caminho, query e fragmento.** Esta rodada nao reduz esse valor a origem: a compatibilidade dos proxies com uma URL minimizada ainda e desconhecida. Tokens ou outros dados sensiveis na query/fragmento da pagina podem assim ser copiados para o `state` OAuth e expostos ao provedor, proxy, historico ou logs de URLs. Evite iniciar a conexao em paginas com esses dados e nao registre `state` nem URLs completas. Fica pendente verificar com os responsaveis pelos proxies se aceitam apenas a origem antes de propor qualquer mudanca coordenada desse contrato.
+
 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:
@@ -158,7 +174,7 @@ if (window.opener) {
 
 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.
+Um login nativo fica em quarentena ate a Meta responder o callback `FB.login` (com codigo, cancelamento ou erro) ou ate a tentativa ter sucesso. O callback, inclusive tardio, libera apenas a quarentena da tentativa a que pertence; nao libera a de outra tentativa. Fechar/cancelar o dialogo ou receber um evento de cancelamento nao garante que esse callback ja tenha chegado. Se um login terminar por timeout, abort ou cancelamento **sem callback**, novas tentativas nativas continuam em `CONNECTION_IN_PROGRESS`: aguarde o callback ou **recarregue a pagina** para tentar outro login nativo. Um callback recebido de cancelamento nao exige reload. Um `FB.login` que falha ao iniciar (excecao sincrona, sem abrir dialogo e sem callback futuro) libera a quarentena imediatamente, sem exigir reload. Essa restricao reduz o risco de atribuir a uma nova tentativa a resposta tardia de um dialogo anterior; 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.
 
@@ -170,26 +186,58 @@ Quando o canal tem app proprio (`appCustom` no `sdk-info`), o SDK muda de compor
 
 | 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 > Dominios permitidos para o SDK do JavaScript | Todas as origens onde o seu site chama `connect` (ex.: `https://app.example.com`), 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.
+Sem o dominio do seu site nos dominios do SDK, a Meta pode recusar o `FB.login`. `PROVIDER_ERROR` depende de a Meta reportar um erro ao SDK; nao e possivel garantir esse codigo para toda falha de dominio. Sem os redirects corretos, o OAuth do Messenger e do Instagram pode ser bloqueado pela Meta. Sem a origem do seu site na allowlist do canal, o SDK resolve com `origin_not_allowed` antes de navegar para a autorizacao; uma janela provisoria ja pode ter sido reservada e sera fechada.
+
+**Inicializacao Meta:** o SDK inicializa uma vez e reutiliza o mesmo `appId` somente quando essa inicializacao foi rastreada pelo proprio SDK. Nao reinicializa silenciosamente o `FB` compartilhado com outro app: quando a pagina nao pode rodar o nativo com seguranca — `FB` do host com inicializacao desconhecida, app conflitante, `appId` retornado pela API que nao e uma string numerica valida ou inicializacao que nao pode ser observada — a tentativa **degrada para o fluxo proxy** na janela reservada, em vez de rejeitar com `INVALID_CONFIGURATION`. Se a janela reservada tiver sido fechada ou bloqueada, a tentativa termina com `popup_closed` ou `POPUP_BLOCKED`. A quarentena de login nativo (`CONNECTION_IN_PROGRESS`) nao degrada: ela protege a atribuicao de callbacks tardios da Meta.
+
+Com o fallback, um `FB` preexistente do host (inclusive de outro app) nao impede mais a conexao: o login acontece na janela da plataforma. Para canais com `appCustom`, isso exige que o **seu** app da Meta conheca o dominio da plataforma, conforme a tabela acima; sem os redirects e dominios corretos, a Meta pode bloquear o fluxo proxy do seu app. Nao reinicialize o `FB` por fora depois que o SDK rastrear seu app. Nao presuma que `direct: false` force proxy nem que `direct: true` garanta nativo: `appCustom`, a origem do frontend e agora a disponibilidade do nativo na pagina tambem decidem o fluxo.
+
+Em SDKs carregados pela biblioteca, chamadas externas ao `FB.init` atual sao encaminhadas normalmente, mas invalidam o app conhecido: uma conexao nativa posterior degrada para o proxy em vez de usar o app errado. Referencias ao `init` original salvas antes dessa observacao nao podem ser monitoradas. Se um script externo expirar sem falha conclusiva, seu carregamento ainda pode terminar: novos SDKs nao recebem proveniencia propria ate recarregar a pagina. O script do host nao e removido.
+
+## Desenvolvimento e verificacao
+
+Use **Node.js 22**, conforme `.nvmrc`, e as dependencias do lockfile:
+
+```bash
+nvm use
+npm ci
+npm run check
+```
+
+`npm run check` executa lint, testes unitarios, build limpo e smoke tests do pacote. Ele limpa os overrides `OMNIZAPI_API_URL` / `OMNIZAPI_FRONT_URL` no ambiente dos subprocessos, sem alterar o ambiente do chamador. A verificacao de release exige os padroes de producao Omnizapi (`https://api.omni.z-api.io` e `https://app.omni.z-api.io`), sem URLs customizadas embutidas no artefato. O lifecycle `prepack` protege automaticamente `npm pack` e `npm publish`; nao use `--ignore-scripts` para contornar essa protecao na preparacao de uma release. A CI faz verificacoes, nao publicacao automatica.
+
+Para os testes locais de navegador, prepare antes os binarios dos tres engines:
+
+```bash
+npm exec playwright install chromium firefox webkit
+npm run test:browser
+```
+
+`test:browser` cobre Chromium, Firefox e WebKit usando o artefato ja compilado: execute `npm run check` antes, pois esse teste nao recompila o SDK. Testes com provedores simulados nao homologam o SDK Meta, os proxies, credenciais ou canais reais; o fluxo nativo e os servicos externos continuam exigindo teste de integracao.
+
+`npm run build` continua permitindo builds customizados com variaveis explicitas `OMNIZAPI_API_URL` e `OMNIZAPI_FRONT_URL`. Isso nao substitui o build com defaults de producao exigido pelo guard de release. As props `apiUrl` / `frontUrl` continuam sendo o modo de configurar o consumidor sem recompilar o SDK.
+
+O hook de versao `scripts/sync-version.mjs` sincroniza os links UNPKG e scripts CDN do README/exemplo vanilla em futuras execucoes aprovadas de `npm version <nova-versao> --no-git-tag-version`. Isso nao publica o pacote.
 
 ## 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.
+- [ ] Antes de uma publicacao futura aprovada, executar as verificacoes e conferir exports default/named `Omnizapi`, tipos na raiz e `dist/omnizapi.min.js`; manter imports, versoes CDN e configuracao dos consumidores coordenados.
+- [ ] Conferir os defaults de producao no artefato de release. Para consumidores customizados, configurar `apiUrl` / `frontUrl` nas props; conferir staging e ambas as URLs de sandbox. Variaveis no build ficam restritas a builds customizados explicitos.
 - [ ] 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`.
+- [ ] Revisar exposicao de query/fragmento em `state.currentUrl`, que permanece completo. Verificar com os proxies a compatibilidade com origem apenas antes de qualquer futura minimizacao; nao assumir suporte.
 - [ ] 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.
+- [ ] Homologar abort, cancelamento com/sem callback Meta (inclusive tardio), fechamento/bloqueio de popup, concorrencia, timeout, conflitos de app ID (que degradam para o fluxo proxy), mensagens de origem/janela/tentativa incorretas e falhas HTTP; validar em servicos reais o gesto do login nativo, a integracao QR e cada canal, inclusive Z-API. Os exemplos nao substituem essa homologacao.
 
 ## Licenca
 
-MIT - FourPixel IT. Autor: FourPixel IT.
+MIT - Copyright (c) 2026 FourPixel IT. Autor: FourPixel IT. Texto completo no arquivo local `LICENSE` e na [licenca do pacote](https://unpkg.com/browse/@omnizapi/connect@1.0.2/LICENSE) apos a publicacao correspondente.