@whanext/core 0.17.1 → 0.18.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.18.1
+
+### Fixed
+
+- Corrige a geração de código de pareamento no Zapo quando o servidor disponibiliza primeiro o fluxo QR (`auth_qr`) em vez de emitir `auth_pairing_required`.
+- O provider agora considera tanto `auth_pairing_required` quanto `auth_qr` como sinais válidos de que `client.auth.requestPairingCode()` pode ser chamado.
+
+## 0.18.0
+
+### Provider Zapo
+
+- O provider padrão foi migrado do Baileys para `zapo-js`, mantendo o contrato público `WhatsAppProvider`.
+- Autenticação e chaves Signal passam a usar store SQLite persistente em `<auth>/state.sqlite`.
+- Mensagens, replies, menções, mídia, view-once, reações, edição, revogação, pin, presença e grupos foram portados para as APIs do Zapo.
+- Eventos `message_protocol`, `group`, `connection` e `voip_call_*` são normalizados para os eventos públicos já existentes do WhaNext.
+- Chamadas continuam suportando rejeição pelo plugin oficial `@zapo-js/voip`.
+- Mensagens do backlog marcadas pelo Zapo como `offline` são ignoradas por padrão; `processOfflineMessages: true` restaura o processamento deliberado do backlog.
+- O cache recente passa a observar também `message_send`, permitindo reenvio de mensagens emitidas pela própria sessão.
+- O carregamento do plugin `@zapo-js/voip` passa a ser dinâmico, evitando que uma instalação sem binário `wrtc` funcional derrube recursos que não usam chamadas.
+- A tipagem de eventos VoIP deixa de perder a extensão de plugin do `WaClient`; `rejectCall` e `voip_call_*` passam por uma ponte tipada local.
+- `recording` é preservado no chatstate conforme a API documentada do Zapo, com adaptação local para a declaração de tipos publicada.
+- O mock do provider Zapo usa `vi.hoisted`, eliminando o acesso a `MockClient` antes da inicialização.
+
+### Migração
+
+- Adicionado `MIGRATING_TO_ZAPO.md` com orientação para novo pareamento ou conversão das sessões multifile antigas.
+- A versão do pacote passa para `0.18.0`.
+
 ## 0.17.1
 
 ### Fixed

package/CONTRIBUTING.md

@@ -5,16 +5,16 @@ Obrigado pelo interesse em melhorar o projeto.
 ## Ambiente
 
 - Node.js 22.5 ou superior
-- npm compatível com o `package-lock.json`
+- npm ou pnpm compatível com o projeto
 
 ```bash
-npm ci
+npm install
 npm run check
 ```
 
 ## Princípios da API
 
-- Baileys permanece restrito ao provider interno.
+- Zapo permanece restrito ao provider interno; a API pública continua independente da implementação.
 - A API pública usa modelos e erros do WhaNext.
 - Operações dependentes de estado retornam resultados tipados e idempotentes.
 - JID, LID e PN são resolvidos pela biblioteca.

package/MIGRATING_TO_ZAPO.md

@@ -0,0 +1,73 @@
+# Migrando do Baileys para Zapo
+
+A v0.18 troca o provider padrão do WhaNext para Zapo. A API pública de comandos, services, mensagens, grupos e multi-account permanece a mesma, mas o formato da sessão muda.
+
+## Sessões
+
+O WhaNext v0.17 e anteriores usava o auth multifile do Baileys, normalmente com `creds.json` e vários arquivos de chaves. O Zapo usa um store persistente e, no provider padrão do WhaNext, esse store fica em:
+
+```text
+<auth>/state.sqlite
+```
+
+Não apague a pasta antiga antes de confirmar que a nova sessão conecta normalmente.
+
+## Opção 1: parear novamente
+
+É o caminho mais simples para uma conta isolada:
+
+1. Faça backup da pasta de auth atual.
+2. Use um diretório limpo para a primeira execução da v0.18.
+3. Inicie o bot e gere um novo pairing code.
+4. Depois de validar mensagens, grupos, mídia e reconexão, arquive a sessão antiga.
+
+## Opção 2: converter a sessão existente
+
+O projeto Zapo fornece o pacote `wa-store-migrate`, que converte o snapshot de autenticação do Baileys para o formato de store do Zapo sem exigir um novo pareamento.
+
+Instale temporariamente no ambiente de migração:
+
+```bash
+npm install wa-store-migrate
+```
+
+A conversão oficial lê `{ creds, keys }` do auth multifile, chama `migrate({ from: 'baileys', to: 'zapo', data })` e grava o resultado em um store Zapo novo. Consulte o guia oficial **Migrating from Baileys** do Zapo para usar o exemplo atualizado da versão que estiver instalada.
+
+No WhaNext, o destino deve ser o `state.sqlite` dentro do diretório `auth` da conta. O `sessionId` precisa ser estável:
+
+- `default` em `create()` quando `accountId` não é informado;
+- o `id` da conta em `createMulti()`.
+
+Converta cada conta separadamente quando usar multi-account.
+
+## Mensagens recebidas após reconexão
+
+O Zapo possui um fluxo explícito de mensagens offline após a conexão. O WhaNext v0.18 protege o router por padrão: eventos que o Zapo marca como `offline` não são encaminhados como mensagens novas. O timestamp da conexão atual também é usado como fallback defensivo quando essa marca não estiver disponível.
+
+Se sua aplicação precisa processar deliberadamente o backlog recebido depois de ficar offline, habilite:
+
+```ts
+const app = await create({
+  processOfflineMessages: true,
+});
+```
+
+## Mídia
+
+O provider usa `@zapo-js/media-utils`. Para processamento completo de imagem, vídeo, áudio e voice note, mantenha `ffmpeg` e `ffprobe` disponíveis no `PATH` do processo.
+
+## Chamadas
+
+O suporte a `app.on('call')` e `rejectCall()` usa o plugin oficial `@zapo-js/voip`. As dependências de runtime do plugin já fazem parte do pacote do WhaNext v0.18.
+
+## Checklist de atualização
+
+- faça backup do auth antigo;
+- instale as dependências da v0.18;
+- converta a sessão ou pareie novamente;
+- valide uma mensagem privada e uma mensagem de grupo;
+- valide LID/PN, reply e menções;
+- valide download de imagem/vídeo e view-once;
+- valide edit/delete se o bot usa anti-edit/anti-delete;
+- valide chamada recebida se o bot usa anti-call;
+- derrube e reconecte o processo e confirme que comandos antigos não são executados.

package/README.md

@@ -31,7 +31,7 @@ await app.login({
 
 ## Por que WhaNext?
 
-- API pública sem objetos ou tipos crus do Baileys.
+- API pública independente do provider, sem objetos ou tipos crus do Zapo.
 - Login por pairing code, sessão persistente e reconexão automática.
 - Uma ou várias contas independentes no mesmo processo com `createMulti()`.
 - Prefixo global e comandos declarativos com argumentos tipados.
@@ -55,6 +55,8 @@ await app.login({
 npm install @whanext/core
 ```
 
+Atualizando da v0.17 ou anterior? Veja [`MIGRATING_TO_ZAPO.md`](./MIGRATING_TO_ZAPO.md) antes de reutilizar a pasta de sessão.
+
 ## Início rápido
 
 ```ts
@@ -306,7 +308,7 @@ if (app.isReady) {
 
 Toda mensagem possui `message.sender: User`. Menções ficam em `message.mentionedUsers`, e o remetente de um reply em `message.quoted?.sender`.
 
-O provider Baileys também classifica o payload em `message.contentKind`, sem exigir acesso aos tipos internos do Baileys ou download da mídia:
+O provider oficial também classifica o payload em `message.contentKind`, sem exigir acesso aos tipos internos do Zapo ou download da mídia:
 
 ```ts
 app.on('message', async (message) => {
@@ -392,7 +394,7 @@ await app.message.buttons(chatId, {
 });
 ```
 
-Também funciona diretamente em replies de comandos, sem importar tipos do Baileys:
+Também funciona diretamente em replies de comandos, sem importar tipos do provider:
 
 ```ts
 await ctx.reply({
@@ -441,7 +443,7 @@ await writeFile(`./downloads/${downloaded.fileName ?? message.id}`, downloaded.d
 
 `download()` aceita a `Message` recebida, uma `QuotedMessage` ou uma `MessageKey` e devolve o buffer junto dos metadados normalizados. A mídia deve ser baixada enquanto a mensagem ainda está no cache da instância; o provider tenta renovar a URL de mídia automaticamente quando necessário.
 
-Para visualização única citada, o provider oficial preserva os metadados do envelope sem expor tipos do Baileys:
+Para visualização única citada, o provider oficial preserva os metadados do envelope sem expor tipos do Zapo:
 
 ```ts
 if (message.quoted?.isViewOnce && message.quoted.hasMedia) {
@@ -453,7 +455,7 @@ if (message.quoted?.isViewOnce && message.quoted.hasMedia) {
 }
 ```
 
-Isso também funciona quando a mídia de visualização única aparece dentro de envelopes `viewOnceMessageV2` ou `viewOnceMessageV2Extension`.
+Isso também funciona quando a mídia de visualização única aparece dentro de envelopes `viewOnceMessage` ou `viewOnceMessageV2`.
 
 Stickers aceitam `Uint8Array`, URL ou caminho local e devem estar em WebP, inclusive para animações. Texto, imagem e vídeo aceitam `User` diretamente em `mentions`.
 
@@ -864,7 +866,7 @@ const app = await create({
 
 O cache padrão vive na instância do app, usa LRU limitado e elimina entradas expiradas durante as leituras. Consultas simultâneas dos mesmos metadados são agrupadas em uma única chamada ao WhatsApp. Eventos e mutações de grupo invalidam automaticamente entradas relacionadas.
 
-Os mesmos metadados também alimentam internamente o `cachedGroupMetadata` do Baileys. Em grupos já aquecidos, isso remove a consulta de metadados do caminho de envio; mensagens continuam aguardando somente criptografia, upload quando houver mídia e confirmação da rede.
+O cache público de metadados continua independente do provider. Eventos e mutações de grupo invalidam as entradas relacionadas, evitando consultas repetidas do bot enquanto os dados ainda estão dentro do TTL.
 
 Para observar um `MemoryCache` criado diretamente:
 
@@ -879,7 +881,7 @@ cache.prune();
 
 `stats()` informa `size`, `maxEntries`, `hits`, `misses`, `sets`, `evictions` e `expirations`.
 
-Para uma única instância, o cache padrão é suficiente mesmo com muitos grupos, desde que `memoryMaxEntries` seja dimensionado. Em várias instâncias/processos, use um `CacheStore` distribuído para o cache público; cada conexão mantém ainda um L1 local limitado para o caminho criptográfico do Baileys. Não compartilhe uma mesma sessão ativa entre processos.
+Para uma única instância, o cache padrão é suficiente mesmo com muitos grupos, desde que `memoryMaxEntries` seja dimensionado. Em várias instâncias/processos, use um `CacheStore` distribuído para o cache público. Cada conexão Zapo mantém seu próprio store de sessão; não compartilhe a mesma sessão ativa entre processos.
 
 O cache interno de mensagens mantém até 1.000 mensagens por padrão para replies, reenvios do provider e downloads de mídia. Ajuste quando necessário:
 

package/dist/index.d.ts

@@ -70,7 +70,7 @@ type MediaKind = 'image' | 'video' | 'audio' | 'document' | 'sticker';
  *
  * `media.kind` remains the source of truth for downloadable media.
  * `contentKind` additionally exposes non-media payloads such as locations,
- * contacts, polls and catalog/product messages without leaking Baileys types.
+ * contacts, polls and catalog/product messages without leaking provider-specific protocol types.
  */
 type MessageContentKind = 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'location' | 'contact' | 'poll' | 'catalog' | 'unknown';
 interface MessageMedia {
@@ -839,6 +839,7 @@ interface CreateOptions {
     router?: Omit<RouterOptions, 'prefix'>;
     reconnect?: ReconnectOptions;
     messageCacheSize?: number;
+    processOfflineMessages?: boolean;
     provider?: WhatsAppProvider;
     accountId?: string;
 }