@whanext/core 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.19.0
+
+### Comandos
+
+- `prefix` passa a aceitar um prefixo único ou uma lista, como `['&', '!', '.']`; o primeiro continua sendo o prefixo principal usado por menus/help.
+- Novo `prefixless` por comando para liberar somente gatilhos explicitamente escolhidos sem prefixo, como `prefixless: ['a']`.
+- `ctx.prefix` agora representa o prefixo que realmente acionou a execução e fica vazio (`''`) em execuções prefixless.
+- `ctx.commands.prefixes` expõe todos os prefixos configurados.
+- Novo `app.commands.setPrefixes()` permite ativar, trocar ou desativar o modo multi-prefixo em runtime sem recriar a aplicação.
+- IDs de respostas de botões/listas são encaminhados ao mesmo router de comandos, permitindo rows como `&open` ou aliases prefixless como `a`.
+
+### Interativos
+
+- Novo envio de enquetes com `PollContent` e `app.message.poll()`.
+- Novo menu de lista single-select com `ListContent`, seções/rows e `app.message.list()`.
+- Botões Native Flow ganham o tipo `reply`, com ID de resposta, além de `copy` e `link`.
+- Mensagens recebidas passam a expor `message.interactive` com `kind`, `id` e título visível quando disponível.
+- Polls recebidas preservam a pergunta em `message.text` e continuam classificadas como `contentKind: 'poll'`.
+
+### Correções
+
+- Corrigida a extração do `contextInfo.quotedMessage`: `extractQuotedZapoMessage()` agora usa o nó real retornado por `contentNode()` em vez do wrapper `{ type, node }`.
+- Quoted messages são armazenadas como mensagens completas no mesmo cache recente do provider, preservando download de mídia e repost.
+- `downloadMedia()` também mantém associação direta com as `MessageKey` emitidas no evento, com fallback por chave/ID para objetos reconstruídos.
+- A correção cobre especialmente respostas a mídias `viewOnceMessageV2Extension`, como `&fig` sobre uma imagem/vídeo de visualização única.
+
+### Compatibilidade
+
+- Configurações existentes com `prefix: '&'` continuam funcionando sem alteração.
+- Nenhum comando se torna prefixless automaticamente; o recurso é opt-in por definição.
+- A API anterior de botões `copy`/`link` permanece compatível.
+
+## 0.18.2
+
+- Corrigida a normalização de mídias de visualização única recebidas no envelope `viewOnceMessageV2Extension` do protocolo do WhatsApp.
+- Replies para imagens e vídeos de visualização única agora expõem corretamente `quoted.hasMedia`, `quoted.isViewOnce`, `quoted.contentKind` e `quoted.media`.
+- O cache de quoted media preserva esse envelope para que `MediaService.download()` consiga recuperar a mídia ao responder comandos como `&fig`.
+
+## 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

package/README.md

@@ -34,7 +34,7 @@ await app.login({
 - 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.
+- Prefixo único ou múltiplos prefixos, aliases prefixless opt-in e comandos declarativos com argumentos tipados.
 - Comandos exclusivos da conta conectada com `guards.owner()` ou `onlyOwner`.
 - Usuários normalizados entre JID, LID e PN.
 - Mensagens, replies, edição, exclusão, revogações, menções, mídias e download normalizado.
@@ -103,7 +103,41 @@ await app.login({
 });
 ```
 
-O prefixo é definido uma vez. O router identifica o comando, remove o prefixo e cria o `ArgsParser` automaticamente.
+O prefixo pode ser único ou múltiplo. O router identifica qual prefixo foi usado, remove apenas esse prefixo e cria o `ArgsParser` automaticamente:
+
+```ts
+const app = await create({
+  prefix: ['&', '!', '.'],
+});
+```
+
+O primeiro valor (`&`, no exemplo) é o prefixo principal usado por `app.commands.prefix` e pelo help automático. Todos ficam disponíveis em `app.commands.prefixes`.
+
+O modo multi-prefixo também pode ser ativado ou trocado em runtime:
+
+```ts
+app.commands.setPrefixes(['&', '!']);
+
+// volta para um único prefixo
+app.commands.setPrefixes('&');
+```
+
+Comandos sem prefixo são **opt-in** e podem liberar somente aliases específicos:
+
+```ts
+app.commands.command(defineCommand({
+  name: 'open',
+  aliases: ['abrir', 'a'],
+  prefixless: ['a'],
+  onlyGroup: true,
+  botMustBeAdmin: true,
+  async execute(ctx) {
+    await ctx.groups.open(ctx.chatId);
+  },
+}));
+```
+
+Nesse exemplo, `&open`, `!open`, `.abrir`, `&a` e `a` funcionam. `open` e `abrir` sem prefixo continuam sendo texto normal. Use `prefixless: true` somente quando quiser liberar sem prefixo o nome e todos os aliases daquele comando.
 
 ## Múltiplas contas
 
@@ -370,9 +404,11 @@ await app.message.react(sent, '👏🏻');
 await app.message.unreact(sent);
 ```
 
-### Botões interativos
+### Interativos
+
+#### Botões
 
-Por enquanto, a API pública suporta botões de **copiar código** e **abrir link**:
+A API pública suporta botões de **copiar**, **abrir link** e **resposta rápida com ID**:
 
 ```ts
 await app.message.buttons(chatId, {
@@ -380,33 +416,74 @@ await app.message.buttons(chatId, {
   text: 'Escolha uma ação:',
   footer: 'WhaNext',
   buttons: [
-    {
-      type: 'copy',
-      label: 'Copiar código',
-      code: 'ABC-123',
-    },
-    {
-      type: 'link',
-      label: 'Abrir painel',
-      url: 'https://example.com',
-    },
+    { type: 'copy', label: 'Copiar código', code: 'ABC-123' },
+    { type: 'link', label: 'Abrir painel', url: 'https://example.com' },
+    { type: 'reply', label: 'Abrir grupo', id: '&open' },
   ],
 });
 ```
 
-Também funciona diretamente em replies de comandos, sem importar tipos do provider:
+Também funciona diretamente em replies de comandos. Quando o usuário toca em um botão `reply`, o ID recebido fica em `message.interactive.id`; se esse ID representa um comando válido, o router o executa automaticamente.
 
 ```ts
 await ctx.reply({
   text: 'Use uma das opções abaixo.',
   buttons: [
-    { type: 'copy', label: 'Copiar', code: 'ABC-123' },
-    { type: 'link', label: 'Abrir site', url: 'https://example.com' },
+    { type: 'reply', label: 'Abrir', id: 'a' },
+    { type: 'link', label: 'Ajuda', url: 'https://example.com' },
+  ],
+});
+```
+
+`title`, `footer` e `mentions` são opcionais. Os tipos podem ser combinados na mesma mensagem.
+
+#### Menu de lista
+
+Para menus maiores, use uma lista single-select com seções e IDs estáveis:
+
+```ts
+await app.message.list(chatId, {
+  title: 'Administração',
+  text: 'Escolha uma ação para o grupo.',
+  buttonText: 'Ver opções',
+  footer: 'WhaNext',
+  list: [
+    {
+      title: 'Grupo',
+      rows: [
+        { id: '&open', title: 'Abrir grupo', description: 'Libera mensagens' },
+        { id: '&close', title: 'Fechar grupo', description: 'Somente admins' },
+      ],
+    },
   ],
 });
 ```
 
-`title`, `footer` e `mentions` são opcionais. Os botões podem ser combinados na mesma mensagem.
+A escolha chega normalizada em `message.interactive`:
+
+```ts
+app.on('message', (message) => {
+  if (message.interactive) {
+    console.log(message.interactive.kind); // 'button' | 'list'
+    console.log(message.interactive.id);
+  }
+});
+```
+
+IDs como `&open` entram no router com prefixo. IDs como `a` entram sem prefixo somente quando aquele gatilho foi liberado com `prefixless`.
+
+#### Enquetes
+
+```ts
+await app.message.poll(chatId, {
+  poll: 'Verdade ou desafio?',
+  options: ['Verdade', 'Desafio'],
+  selectableCount: 1,
+  allowAddOption: false,
+});
+```
+
+`selectableCount` é opcional e assume `1`. A pergunta de uma poll recebida também fica disponível em `message.text`, com `message.contentKind === 'poll'`.
 
 `delete()` aceita `Message`, `SentMessage` ou `MessageKey`.
 
@@ -839,7 +916,7 @@ export default defineCommand({
 });
 ```
 
-`ctx.commands` fornece `catalog()`, `categories()`, `find()`, `has()`, `size` e `prefix`; ele não expõe detalhes internos do provider.
+`ctx.commands` fornece `catalog()`, `categories()`, `find()`, `has()`, `size`, `prefix` e `prefixes`; ele não expõe detalhes internos do provider. `ctx.prefix` contém o prefixo que acionou aquela execução e é `''` quando o comando foi disparado por um gatilho prefixless.
 
 Se for necessário controlar extensões ou recursão:
 

package/dist/index.d.ts

@@ -90,6 +90,12 @@ interface QuotedMessage {
     contentKind?: MessageContentKind;
     media?: MessageMedia;
 }
+type InteractiveResponseKind = 'button' | 'list';
+interface InteractiveResponse {
+    kind: InteractiveResponseKind;
+    id: string;
+    title?: string;
+}
 interface MessageDeleted {
     key: MessageKey;
     message?: Message;
@@ -128,6 +134,7 @@ interface Message {
     contentKind?: MessageContentKind;
     media?: MessageMedia;
     quoted?: QuotedMessage;
+    interactive?: InteractiveResponse;
 }
 interface SentMessage {
     id: string;
@@ -164,7 +171,12 @@ interface CopyCodeButton {
     label: string;
     code: string;
 }
-type MessageButton = LinkButton | CopyCodeButton;
+interface QuickReplyButton {
+    type: 'reply';
+    label: string;
+    id: string;
+}
+type MessageButton = LinkButton | CopyCodeButton | QuickReplyButton;
 interface ButtonsContent {
     text: string;
     buttons: MessageButton[];
@@ -172,6 +184,29 @@ interface ButtonsContent {
     footer?: string;
     mentions?: MentionTarget[];
 }
+interface ListRow {
+    id: string;
+    title: string;
+    description?: string;
+}
+interface ListSection {
+    title?: string;
+    rows: readonly ListRow[];
+}
+interface ListContent {
+    list: readonly ListSection[];
+    text: string;
+    buttonText: string;
+    title?: string;
+    footer?: string;
+    mentions?: MentionTarget[];
+}
+interface PollContent {
+    poll: string;
+    options: readonly string[];
+    selectableCount?: number;
+    allowAddOption?: boolean;
+}
 interface ImageContent {
     image: MediaSource;
     caption?: string;
@@ -193,7 +228,7 @@ interface AudioContent {
 interface StickerContent {
     sticker: MediaSource;
 }
-type MessageContent = TextContent | ButtonsContent | ImageContent | VideoContent | AudioContent | StickerContent;
+type MessageContent = TextContent | ButtonsContent | ListContent | PollContent | ImageContent | VideoContent | AudioContent | StickerContent;
 
 type GroupAccess = 'open' | 'closed';
 type GroupRole = 'member' | 'admin' | 'owner';
@@ -494,10 +529,13 @@ declare class MessageService {
     unreact(message: Message | SentMessage | MessageKey): Promise<SentMessage>;
     text(chatId: string, text: string, mentions?: MentionTarget[]): Promise<SentMessage>;
     buttons(chatId: string, content: ButtonsContent): Promise<SentMessage>;
+    list(chatId: string, content: ListContent): Promise<SentMessage>;
+    poll(chatId: string, content: PollContent): Promise<SentMessage>;
 }
 
 interface CommandCatalogView {
     readonly prefix: string;
+    readonly prefixes: readonly string[];
     readonly size: number;
     catalog(options?: {
         category?: string;
@@ -628,6 +666,7 @@ interface CommandMetadata {
     name: string;
     description: string;
     aliases?: readonly string[];
+    prefixless?: boolean | readonly string[];
     category?: string;
     usage?: string;
     examples?: readonly string[];
@@ -684,7 +723,7 @@ interface LoadedCommand {
 declare function loadCommands(registrar: CommandRegistrar, dirPath: string | URL, options?: LoadCommandsOptions): Promise<LoadCommandsResult>;
 
 interface RouterOptions {
-    prefix?: string;
+    prefix?: string | readonly string[];
     onError?: (error: WhaNextError, message: Message) => void | Promise<void>;
     onCommandError?: CommandErrorHandler;
     beforeExecute?: (context: CommandContext) => void | Promise<void>;
@@ -703,6 +742,8 @@ declare class CommandRouter {
     constructor(services: CommandRuntimeServices, options?: RouterOptions);
     constructor(group: GroupService, options?: RouterOptions);
     get prefix(): string;
+    get prefixes(): readonly string[];
+    setPrefixes(prefixes: string | readonly string[]): this;
     get size(): number;
     command(definition: CommandDefinition): this;
     load(dirPath: string | URL, options?: LoadCommandsOptions): Promise<LoadCommandsResult>;
@@ -787,7 +828,7 @@ interface AppHealth {
 }
 interface WhaNextAppOptions {
     phone?: string;
-    prefix?: string;
+    prefix?: string | readonly string[];
     cache?: CacheOptions;
     logger?: LoggerConfig;
     mute?: MuteOptions;
@@ -832,7 +873,7 @@ interface CreateOptions {
     phone?: string;
     browser?: Browser;
     auth?: string;
-    prefix?: string;
+    prefix?: string | readonly string[];
     cache?: CacheOptions;
     logger?: LoggerConfig;
     mute?: MuteOptions;
@@ -925,4 +966,4 @@ declare class SqliteMuteStore implements MuteStore {
     close(): void;
 }
 
-export { AccountService, type AddMuteOptions, type AddMuteResult, type AppEvents, type AppHealth, type AppHealthStatus, ArgsParser, type AudioContent, type BooleanOption, Browser, type ButtonsContent, type CacheOptions, type CacheStore, type CallEvent, type CallStatus, type ChangeResult, type CommandAccountContext, type CommandCatalogOptions, type CommandCatalogView, type CommandChatContext, type CommandConcurrency, type CommandContext, type CommandCooldown, type CommandDefinition, type CommandErrorHandler, type CommandGroupContext, type CommandGroupDefinition, type CommandGuard, type CommandHelpOptions, type CommandHooks, type CommandLocalization, type CommandMetadata, type CommandMiddleware, type CommandOptionDefinition, type CommandOptionSchema, type CommandOptionValue, type CommandOptionValues, type CommandRegistrar, CommandRouter, type CommandRuntimeServices, type CommandScope, type ConcurrencyStrategy, type ConnectionState, type ConnectionUpdate, type CopyCodeButton, type CreateMultiOptions, type CreateOptions, DeferredReply, type DownloadedMedia, type DurationOption, type EnumOption, type ExecutableCommandDefinition, type GroupAccess, type GroupAddressingMode, type GroupParticipant, type GroupParticipantAction, type GroupParticipantsChanged, type GroupRole, type GroupSnapshot, type GuardResult, type ImageContent, type InviteResult, type LinkButton, type LoadCommandsOptions, type LoadCommandsResult, type LoadedCommand, type LogContext, type LogEntry, type LogFormat, type LogLevel, type LogWriter, Logger, type LoggerConfig, type LoggerOptions, type LoginOptions, type MediaKind, type MediaSource, type MemberActionState, MemoryCache, type MemoryCacheStats, type MentionTarget, type Message, type MessageButton, type MessageContent, type MessageContentKind, type MessageDeleted, type MessageEdited, type MessageKey, type MessageMedia, type MultiAccountOptions, type MultiAppEvent, type MultiAppHealth, MultiCommandRouter, type MultiLoadCommandsResult, type MultiLoginOptions, type MuteChangeResult, type MuteEnforcement, type MuteOptions, type MuteRecord, MuteService, type MuteStore, type NumberOption, ParsedCommandOptions, type ParticipantUpdateResult, type PresenceState, type QuotedMessage, type ReconnectOptions, type RegisteredCommand, type RemoveMuteResult, type ReplyOptions, type RepostMessageOptions, type RouterOptions, type SentMessage, SqliteMuteStore, type StickerContent, type StoredMute, type StringOption, type TextContent, User, type UserData, type UserOption, type VideoContent, WhaNextApp, WhaNextError, type WhaNextErrorCode, WhaNextMultiApp, type WhatsAppProvider, create, createMulti, defineCommand, defineCommandGroup, defineCommands, defineSubcommand, guards, isCommandGroup, loadCommands, option, toWhaNextError };
+export { AccountService, type AddMuteOptions, type AddMuteResult, type AppEvents, type AppHealth, type AppHealthStatus, ArgsParser, type AudioContent, type BooleanOption, Browser, type ButtonsContent, type CacheOptions, type CacheStore, type CallEvent, type CallStatus, type ChangeResult, type CommandAccountContext, type CommandCatalogOptions, type CommandCatalogView, type CommandChatContext, type CommandConcurrency, type CommandContext, type CommandCooldown, type CommandDefinition, type CommandErrorHandler, type CommandGroupContext, type CommandGroupDefinition, type CommandGuard, type CommandHelpOptions, type CommandHooks, type CommandLocalization, type CommandMetadata, type CommandMiddleware, type CommandOptionDefinition, type CommandOptionSchema, type CommandOptionValue, type CommandOptionValues, type CommandRegistrar, CommandRouter, type CommandRuntimeServices, type CommandScope, type ConcurrencyStrategy, type ConnectionState, type ConnectionUpdate, type CopyCodeButton, type CreateMultiOptions, type CreateOptions, DeferredReply, type DownloadedMedia, type DurationOption, type EnumOption, type ExecutableCommandDefinition, type GroupAccess, type GroupAddressingMode, type GroupParticipant, type GroupParticipantAction, type GroupParticipantsChanged, type GroupRole, type GroupSnapshot, type GuardResult, type ImageContent, type InteractiveResponse, type InteractiveResponseKind, type InviteResult, type LinkButton, type ListContent, type ListRow, type ListSection, type LoadCommandsOptions, type LoadCommandsResult, type LoadedCommand, type LogContext, type LogEntry, type LogFormat, type LogLevel, type LogWriter, Logger, type LoggerConfig, type LoggerOptions, type LoginOptions, type MediaKind, type MediaSource, type MemberActionState, MemoryCache, type MemoryCacheStats, type MentionTarget, type Message, type MessageButton, type MessageContent, type MessageContentKind, type MessageDeleted, type MessageEdited, type MessageKey, type MessageMedia, type MultiAccountOptions, type MultiAppEvent, type MultiAppHealth, MultiCommandRouter, type MultiLoadCommandsResult, type MultiLoginOptions, type MuteChangeResult, type MuteEnforcement, type MuteOptions, type MuteRecord, MuteService, type MuteStore, type NumberOption, ParsedCommandOptions, type ParticipantUpdateResult, type PollContent, type PresenceState, type QuickReplyButton, type QuotedMessage, type ReconnectOptions, type RegisteredCommand, type RemoveMuteResult, type ReplyOptions, type RepostMessageOptions, type RouterOptions, type SentMessage, SqliteMuteStore, type StickerContent, type StoredMute, type StringOption, type TextContent, User, type UserData, type UserOption, type VideoContent, WhaNextApp, WhaNextError, type WhaNextErrorCode, WhaNextMultiApp, type WhatsAppProvider, create, createMulti, defineCommand, defineCommandGroup, defineCommands, defineSubcommand, guards, isCommandGroup, loadCommands, option, toWhaNextError };