@whanext/core 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 Todas as mudanças relevantes do projeto serão registradas neste arquivo.
 
+## 0.7.0
+
+### Adicionado
+
+- `app.message.react(message, emoji)` e `app.message.unreact(message)` para adicionar e remover reações sem expor tipos do provider.
+- Evento `groupParticipantsChanged`, com grupo, ação, participantes afetados e autor quando informado pelo WhatsApp.
+
+### Alterado
+
+- Alterações de participantes continuam invalidando automaticamente o cache de metadados do grupo antes da emissão do evento público.
+
+## 0.6.0
+
+### Adicionado
+
+- `app.media.download(message)` para baixar imagens, vídeos, áudios, documentos e stickers recebidos como um `Buffer` com metadados normalizados.
+- Renovação automática da URL de mídia quando o link original expira.
+- Configurações `cache.memoryMaxEntries` e `messageCacheSize` para limitar a memória usada pelos caches internos.
+
+### Alterado
+
+- O cache em memória agora usa LRU e agrupa buscas simultâneas dos metadados do mesmo grupo em uma única consulta ao WhatsApp.
+- O cache de mensagens usa a chave completa da conversa, evitando colisões entre mensagens de chats distintos, e mantém até 1.000 entradas por padrão.
+- Envio de presença deixou de fazer uma assinatura remota antes de cada atualização, reduzindo uma ida extra à rede para `typing`, `recording` e `paused`.
+
+## 0.5.1
+
+### Adicionado
+
+- `defineCommands(...commands)` para declarar vários comandos no mesmo módulo com inferência completa de tipos.
+- `LoadCommandsResult.commands`, com o nome e o arquivo de origem de cada comando registrado.
+
+### Alterado
+
+- `loadCommands()` agora descobre todos os comandos exportados por um arquivo, incluindo vários exports nomeados e coleções exportadas por padrão.
+- Exports auxiliares são ignorados quando o módulo possui comandos válidos.
+- O mesmo objeto de comando não é registrado duas vezes quando aparece em mais de um export.
+- A ordem de descoberta dos arquivos agora é determinística.
+
+### Corrigido
+
+- Corrigido o autoload que registrava apenas o primeiro comando de arquivos como `mute/unmute`.
+
 ## 0.5.0
 
 ### Adicionado

package/CONTRIBUTING.md

@@ -18,6 +18,9 @@ npm run check
 - 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.
+- Mídias são expostas por modelos normalizados; tipos e objetos do provider não entram na API pública.
+- APIs de presença não devem adicionar chamadas remotas além da atualização de estado solicitada.
+- Caches internos devem ter limite de memória, TTL quando aplicável e cobertura para concorrência.
 - Novos comportamentos possuem testes sem conexão real com o WhatsApp.
 - Imports com vários nomes mantêm um nome por linha.
 - Código-fonte não contém comentários explicando implementação óbvia.

package/README.md

@@ -35,7 +35,7 @@ await app.login({
 - Login por pairing code, sessão persistente e reconexão automática.
 - Prefixo global e comandos declarativos com argumentos tipados.
 - Usuários normalizados entre JID, LID e PN.
-- Mensagens, replies, edição, exclusão, menções e mídias.
+- Mensagens, replies, edição, exclusão, menções, mídias e download normalizado.
 - Operações de grupos e membros com resultados idempotentes.
 - Cache de metadados transparente e substituível.
 - Mute permanente ou temporário com SQLite ou banco próprio.
@@ -261,10 +261,15 @@ await app.message.reply(message, {
 
 await app.message.edit(sent, 'Texto atualizado.');
 await app.message.delete(sent);
+
+await app.message.react(sent, '👏🏻');
+await app.message.unreact(sent);
 ```
 
 `delete()` aceita `Message`, `SentMessage` ou `MessageKey`.
 
+`react()` aceita os mesmos tipos e adiciona uma reação à mensagem. `unreact()` remove a reação da conta conectada.
+
 ## Mídias
 
 ```ts
@@ -284,8 +289,14 @@ await app.media.audio(chatId, {
   mimetype: 'audio/ogg; codecs=opus',
   voice: true,
 });
+
+const downloaded = await app.media.download(message);
+
+await writeFile(`./downloads/${downloaded.fileName ?? message.id}`, downloaded.data);
 ```
 
+`download()` aceita a `Message` recebida ou a sua `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.
+
 Texto, imagem e vídeo aceitam `User` diretamente em `mentions`.
 
 ## Grupos e membros
@@ -305,6 +316,19 @@ await app.member.demote(groupId, user);
 
 Estados como `already_open`, `already_admin`, `not_admin`, `not_in_group` e `already_removed` evitam mutações redundantes. A biblioteca escolhe automaticamente a identidade correta para grupos LID ou PN e só retorna sucesso depois da confirmação do WhatsApp.
 
+Mudanças feitas por outros participantes podem ser acompanhadas sem lidar com o provider:
+
+```ts
+app.on('groupParticipantsChanged', async (change) => {
+  console.log(change.groupId);
+  console.log(change.action);
+  console.log(change.participantIds);
+  console.log(change.authorId);
+});
+```
+
+`action` pode ser `add`, `remove`, `promote`, `demote` ou `modify`. O cache de metadados do grupo é invalidado antes desse evento ser emitido.
+
 ## Mute nativo
 
 Quando habilitado, o mute é aplicado antes dos eventos públicos e do router. Mensagens de um usuário mutado são apagadas automaticamente.
@@ -409,7 +433,7 @@ Restrições disponíveis:
 
 ### Carregando comandos de uma pasta
 
-`loadCommands` importa e registra todos os comandos de um diretório, sem precisar listar cada arquivo manualmente:
+`loadCommands` importa e registra todos os comandos de um diretório, sem precisar listar cada arquivo manualmente. Um arquivo pode conter um ou vários comandos:
 
 ```ts
 import { loadCommands } from '@whanext/core';
@@ -417,7 +441,7 @@ import { loadCommands } from '@whanext/core';
 await loadCommands(app.router(), './commands');
 ```
 
-Cada arquivo deve exportar um `CommandDefinition`, por padrão ou nomeado:
+Para um comando por arquivo, continue usando `defineCommand` normalmente:
 
 ```ts
 // commands/ping.js
@@ -430,6 +454,40 @@ export default defineCommand({
 });
 ```
 
+Para manter comandos relacionados juntos, use `defineCommands`. Esse é o formato recomendado para módulos com vários comandos:
+
+```ts
+// commands/moderation.ts
+import { defineCommand, defineCommands } from '@whanext/core';
+
+const mute = defineCommand({
+  name: 'mute',
+  description: 'Silencia um membro.',
+  async execute(message, args) {
+    // ...
+  },
+});
+
+const unmute = defineCommand({
+  name: 'unmute',
+  description: 'Remove o silêncio de um membro.',
+  async execute(message, args) {
+    // ...
+  },
+});
+
+export default defineCommands(mute, unmute);
+```
+
+Vários exports nomeados também são descobertos automaticamente:
+
+```ts
+export const mute = defineCommand({ /* ... */ });
+export const unmute = defineCommand({ /* ... */ });
+```
+
+Exports auxiliares, como constantes e metadados, são ignorados quando o módulo contém ao menos um comando válido. Se o mesmo objeto de comando aparecer em uma coleção e em um export nomeado, ele será registrado apenas uma vez.
+
 Por padrão, `loadCommands` procura arquivos `.js`, `.mjs` e `.cjs`, incluindo subpastas. Extensões como `.ts` não são carregadas por padrão, já que o `import()` dinâmico depende de um loader do TypeScript já estar ativo no processo (`tsx`, `ts-node` ou similar); habilite explicitamente quando esse loader existir:
 
 ```ts
@@ -438,6 +496,16 @@ await loadCommands(app.router(), './commands', { extensions: ['.ts'] });
 
 `loadCommands` também aceita qualquer objeto com um método `command()`, não apenas o router retornado por `app.router()`.
 
+O retorno informa os arquivos carregados e ignorados, além de cada comando registrado:
+
+```ts
+const result = await loadCommands(app.router(), './commands');
+
+console.log(result.loaded);   // arquivos importados
+console.log(result.skipped);  // extensões não habilitadas
+console.log(result.commands); // { name, filePath }[]
+```
+
 ## Cache externo
 
 ```ts
@@ -445,11 +513,18 @@ const app = await create({
   cache: {
     store: myRedisStore,
     groupTtlMs: 300_000,
+    memoryMaxEntries: 1_000,
   },
 });
 ```
 
-O cache padrão vive na instância do app. Eventos e mutações de grupo invalidam automaticamente entradas relacionadas.
+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.
+
+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:
+
+```ts
+const app = await create({ messageCacheSize: 2_000 });
+```
 
 ## Presença
 
@@ -459,6 +534,8 @@ await app.chat.recording(chatId);
 await app.chat.stopTyping(chatId);
 ```
 
+`typing()` envia `composing`, `recording()` envia `recording` com mídia de áudio e `stopTyping()` envia `paused`, conforme o protocolo do WhatsApp. Nenhuma assinatura de presença desnecessária é feita antes do envio.
+
 ## Chamadas
 
 ```ts
@@ -489,8 +566,8 @@ Todos os erros públicos usam `WhaNextError` e códigos estáveis. O logger regi
 
 | Domínio | Responsabilidade |
 | --- | --- |
-| `app.message` | Envio, reply, edição, exclusão e texto |
-| `app.media` | Imagem, vídeo e áudio |
+| `app.message` | Envio, reply, edição, exclusão, texto e reações |
+| `app.media` | Envio e download de mídia |
 | `app.group` | Estado, convite, pin e metadados |
 | `app.member` | Remoção, promoção e rebaixamento |
 | `app.user` | Criação e resolução de usuários |
@@ -500,6 +577,7 @@ Todos os erros públicos usam `WhaNextError` e códigos estáveis. O logger regi
 | `app.router()` | Registro e despacho de comandos |
 | `loadCommands()` | Autoload de comandos a partir de uma pasta |
 | `app.health()` | Snapshot de saúde da aplicação |
+| `app.on('groupParticipantsChanged')` | Alterações de participantes em grupos |
 
 ## Exemplo executável
 

package/SECURITY.md

@@ -4,7 +4,7 @@
 
 | Versão | Suporte |
 | --- | --- |
-| 0.3.x | Sim |
+| 0.7.x | Sim |
 | anteriores | Não |
 
 ## Reportando uma vulnerabilidade

package/dist/index.d.ts

@@ -7,6 +7,7 @@ interface CacheStore {
 interface CacheOptions {
     store?: CacheStore;
     groupTtlMs?: number;
+    memoryMaxEntries?: number;
 }
 
 interface UserData {
@@ -107,6 +108,12 @@ interface SentMessage {
     keys: MessageKey;
     timestamp: Date;
 }
+interface DownloadedMedia {
+    data: Buffer;
+    kind: MediaKind;
+    mimetype?: string;
+    fileName?: string;
+}
 type MediaSource = Uint8Array | {
     url: string;
 } | {
@@ -148,8 +155,9 @@ interface CommandDefinition {
     execute(message: Message, args: ArgsParser): void | Promise<void>;
 }
 declare function defineCommand<const Command extends CommandDefinition>(command: Command): Command;
+declare function defineCommands<const Commands extends readonly CommandDefinition[]>(...commands: Commands): Commands;
 
-type WhaNextErrorCode = 'AUTH_INVALID_PHONE' | 'AUTH_EXPIRED' | 'CONNECTION_CLOSED' | 'CONNECTION_FAILED' | 'GROUP_NOT_FOUND' | 'MEMBER_NOT_FOUND' | 'BOT_NOT_ADMIN' | 'MESSAGE_NOT_FOUND' | 'MUTE_DISABLED' | 'STORAGE_ERROR' | 'ARGUMENT_MISSING' | 'ARGUMENT_INVALID' | 'COMMAND_NOT_ALLOWED' | 'COMMAND_LOAD_FAILED' | 'PROVIDER_ERROR' | 'UNKNOWN_ERROR';
+type WhaNextErrorCode = 'AUTH_INVALID_PHONE' | 'AUTH_EXPIRED' | 'CONNECTION_CLOSED' | 'CONNECTION_FAILED' | 'GROUP_NOT_FOUND' | 'MEMBER_NOT_FOUND' | 'BOT_NOT_ADMIN' | 'MESSAGE_NOT_FOUND' | 'MEDIA_NOT_AVAILABLE' | 'MUTE_DISABLED' | 'STORAGE_ERROR' | 'ARGUMENT_MISSING' | 'ARGUMENT_INVALID' | 'COMMAND_NOT_ALLOWED' | 'COMMAND_LOAD_FAILED' | 'PROVIDER_ERROR' | 'UNKNOWN_ERROR';
 interface WhaNextErrorOptions {
     cause?: unknown;
     context?: Readonly<Record<string, unknown>>;
@@ -166,6 +174,13 @@ declare function toWhaNextError(error: unknown, context?: Readonly<Record<string
 type GroupAccess = 'open' | 'closed';
 type GroupRole = 'member' | 'admin' | 'owner';
 type GroupAddressingMode = 'lid' | 'pn';
+type GroupParticipantAction = 'add' | 'remove' | 'promote' | 'demote' | 'modify';
+interface GroupParticipantsChanged {
+    groupId: string;
+    action: GroupParticipantAction;
+    participantIds: string[];
+    authorId?: string;
+}
 interface GroupParticipant {
     id: string;
     lid?: string;
@@ -227,6 +242,7 @@ interface ProviderEvents {
     groupChanged: {
         groupId: string;
     };
+    groupParticipantsChanged: GroupParticipantsChanged;
     call: CallEvent;
 }
 type Unsubscribe = () => void;
@@ -237,6 +253,8 @@ interface WhatsAppProvider {
     requestPairingCode(phone: string): Promise<string>;
     on<Event extends keyof ProviderEvents>(event: Event, listener: (payload: ProviderEvents[Event]) => void | Promise<void>): Unsubscribe;
     sendMessage(chatId: string, content: MessageContent, replyTo?: MessageKey): Promise<SentMessage>;
+    reactToMessage(key: MessageKey, emoji?: string): Promise<SentMessage>;
+    downloadMedia(key: MessageKey): Promise<DownloadedMedia>;
     editMessage(key: MessageKey, content: string): Promise<SentMessage>;
     deleteMessage(key: MessageKey): Promise<void>;
     getGroup(groupId: string): Promise<GroupSnapshot>;
@@ -392,6 +410,7 @@ declare class MediaService {
     image(chatId: string, content: ImageContent): Promise<SentMessage>;
     video(chatId: string, content: VideoContent): Promise<SentMessage>;
     audio(chatId: string, content: AudioContent): Promise<SentMessage>;
+    download(message: Message | MessageKey): Promise<DownloadedMedia>;
 }
 
 declare class MemberService {
@@ -409,6 +428,8 @@ declare class MessageService {
     reply(message: Message, content: MessageContent): Promise<SentMessage>;
     edit(message: Message | SentMessage | MessageKey, text: string): Promise<SentMessage>;
     delete(message: Message | SentMessage | MessageKey): Promise<void>;
+    react(message: Message | SentMessage | MessageKey, emoji: string): Promise<SentMessage>;
+    unreact(message: Message | SentMessage | MessageKey): Promise<SentMessage>;
     text(chatId: string, text: string, mentions?: MentionTarget[]): Promise<SentMessage>;
 }
 
@@ -425,6 +446,7 @@ interface AppEvents {
     error: WhaNextError;
     mute: MuteEnforcement;
     call: CallEvent;
+    groupParticipantsChanged: GroupParticipantsChanged;
 }
 interface LoginOptions {
     onCode?: (code: string) => void | Promise<void>;
@@ -490,12 +512,16 @@ interface CreateOptions {
     mute?: MuteOptions;
     router?: Omit<RouterOptions, 'prefix'>;
     reconnect?: ReconnectOptions;
+    messageCacheSize?: number;
     provider?: WhatsAppProvider;
 }
 declare function create(options?: CreateOptions): Promise<WhaNextApp>;
 
 declare class MemoryCache implements CacheStore {
     #private;
+    constructor(options?: {
+        maxEntries?: number;
+    });
     get<T>(key: string): Promise<T | undefined>;
     set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
     delete(key: string): Promise<void>;
@@ -512,6 +538,11 @@ interface LoadCommandsOptions {
 interface LoadCommandsResult {
     loaded: readonly string[];
     skipped: readonly string[];
+    commands: readonly LoadedCommand[];
+}
+interface LoadedCommand {
+    name: string;
+    filePath: string;
 }
 declare function loadCommands(registrar: CommandRegistrar, dirPath: string, options?: LoadCommandsOptions): Promise<LoadCommandsResult>;
 
@@ -525,4 +556,4 @@ declare class SqliteMuteStore implements MuteStore {
     close(): void;
 }
 
-export { type AddMuteOptions, type AddMuteResult, type AppEvents, type AppHealth, type AppHealthStatus, ArgsParser, type AudioContent, Browser, type CacheOptions, type CacheStore, type CallEvent, type CallStatus, type ChangeResult, type CommandDefinition, type CommandRegistrar, CommandRouter, type ConnectionState, type ConnectionUpdate, type CreateOptions, type GroupAccess, type GroupAddressingMode, type GroupParticipant, type GroupRole, type GroupSnapshot, type ImageContent, type InviteResult, type LoadCommandsOptions, type LoadCommandsResult, 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 MentionTarget, type Message, type MessageContent, type MessageKey, type MessageMedia, type MuteChangeResult, type MuteEnforcement, type MuteOptions, type MuteRecord, MuteService, type MuteStore, type ParticipantUpdateResult, type PresenceState, type QuotedMessage, type ReconnectOptions, type RemoveMuteResult, type RouterOptions, type SentMessage, SqliteMuteStore, type StoredMute, type TextContent, User, type UserData, type VideoContent, WhaNextApp, WhaNextError, type WhaNextErrorCode, type WhatsAppProvider, create, defineCommand, loadCommands, toWhaNextError };
+export { type AddMuteOptions, type AddMuteResult, type AppEvents, type AppHealth, type AppHealthStatus, ArgsParser, type AudioContent, Browser, type CacheOptions, type CacheStore, type CallEvent, type CallStatus, type ChangeResult, type CommandDefinition, type CommandRegistrar, CommandRouter, type ConnectionState, type ConnectionUpdate, type CreateOptions, type DownloadedMedia, type GroupAccess, type GroupAddressingMode, type GroupParticipant, type GroupParticipantAction, type GroupParticipantsChanged, type GroupRole, type GroupSnapshot, type ImageContent, type InviteResult, 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 MentionTarget, type Message, type MessageContent, type MessageKey, type MessageMedia, type MuteChangeResult, type MuteEnforcement, type MuteOptions, type MuteRecord, MuteService, type MuteStore, type ParticipantUpdateResult, type PresenceState, type QuotedMessage, type ReconnectOptions, type RemoveMuteResult, type RouterOptions, type SentMessage, SqliteMuteStore, type StoredMute, type TextContent, User, type UserData, type VideoContent, WhaNextApp, WhaNextError, type WhaNextErrorCode, type WhatsAppProvider, create, defineCommand, defineCommands, loadCommands, toWhaNextError };