@whanext/core 0.13.1 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.14.1
+
+### Corrigido
+
+- A normalização agora preserva corretamente o envelope de visualização única (`viewOnceMessage`, `viewOnceMessageV2` e `viewOnceMessageV2Extension`) antes de desembrulhar a mídia.
+- `message.isViewOnce` passa a ser verdadeiro mesmo quando o Baileys representa a visualização única apenas pelo wrapper externo.
+- Mensagens citadas agora expõem `quoted.isViewOnce`, `quoted.contentKind` e `quoted.media`, permitindo distinguir mídia normal de visualização única sem heurísticas na aplicação.
+- `app.media.download()` aceita diretamente uma `QuotedMessage`, permitindo `app.media.download(message.quoted)` quando houver mídia citada.
+- `app.account.jid`, `app.account.lid`, `app.account.phoneNumber` e `app.account.selfChatId` expõem identidades canônicas da própria conta. `selfChatId` prioriza PN JID sem sufixo de dispositivo antes de usar LID.
+
+### Compatibilidade
+
+- Os novos campos de `QuotedMessage` são opcionais no contrato público para não quebrar providers customizados ou objetos criados manualmente. O provider Baileys oficial os preenche nas mensagens normalizadas.
+- `app.media.download(message)` e `app.media.download(message.keys)` continuam funcionando sem alteração.
+
+## 0.14.0
+
+### Adicionado
+
+- `guards.owner()` para restringir comandos à própria conta conectada ao WhatsApp.
+- `onlyOwner: true` para manter o mesmo recurso disponível na API legada de comandos.
+- `ctx.isOwner` e `ctx.account` no contexto moderno; em multi-account, `ctx.account.id` identifica qual conta executou o comando.
+- `app.account` com os identificadores atuais da conta e `isOwner(message)` sem exigir JID, LID ou número manual.
+- `createMulti()` e `WhaNextMultiApp` para manter várias contas independentes no mesmo processo.
+- `multi.commands` para registrar comandos, middleware, handlers de erro e autoload em todas as contas da instância.
+- `multi.login()`, `multi.disconnect()`, `multi.health()`, `multi.get()`, `multi.ids()` e `multi.isReady` para operar as contas em conjunto.
+- `multi.on()` para observar eventos de todas as contas com `accountId`, aplicação e payload de origem.
+- Sessões automáticas isoladas em `./sessions/<id>` quando `auth` não é informado.
+- Banco de mute automático separado por conta (`./data/whanext-<id>.sqlite`) quando o mute é habilitado sem banco/store explícito.
+
+### Segurança e compatibilidade
+
+- IDs de contas multi-account são validados para impedir caminhos de sessão inseguros.
+- Diretórios `auth` duplicados são rejeitados entre contas que usam o provider padrão.
+- `create()` e toda a API de uma única conta continuam compatíveis.
+- Cada conta mantém provider, socket, sessão, cache, reconexão e identidade próprios; nenhuma sessão ativa é compartilhada entre contas.
+
 ## 0.13.1
 
 - Corrigido download de mídias para mensagens visualização única citadas, através do cache do payload citado carregado em `contextInfo`.

package/README.md

@@ -33,7 +33,9 @@ await app.login({
 
 - API pública sem objetos ou tipos crus do Baileys.
 - 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.
+- Comandos exclusivos da conta conectada com `guards.owner()` ou `onlyOwner`.
 - Usuários normalizados entre JID, LID e PN.
 - Mensagens, replies, edição, exclusão, menções, mídias e download normalizado.
 - Operações de grupos e membros com resultados idempotentes.
@@ -101,6 +103,62 @@ await app.login({
 
 O prefixo é definido uma vez. O router identifica o comando, remove o prefixo e cria o `ArgsParser` automaticamente.
 
+## Múltiplas contas
+
+Para manter duas, três ou mais contas de WhatsApp no mesmo processo, use `createMulti()`. Cada conta possui conexão, sessão, cache, reconexão e identidade próprios. A instância conjunta apenas coordena essas aplicações independentes.
+
+```ts
+import {
+  Browser,
+  createMulti,
+  defineCommand,
+  guards,
+} from '@whanext/core';
+
+const multi = await createMulti({
+  prefix: ';',
+  browser: Browser.Windows,
+  authRoot: './sessions',
+  logger: 'info',
+  accounts: [
+    { id: 'principal', phone: process.env.PHONE_1 },
+    { id: 'secundaria', phone: process.env.PHONE_2 },
+    { id: 'terceira', phone: process.env.PHONE_3 },
+  ],
+});
+
+multi.commands.command(defineCommand({
+  name: 'painel',
+  description: 'Exibe um painel exclusivo do dono.',
+  guards: [guards.owner()],
+  async execute(ctx) {
+    await ctx.reply(`Conta: ${ctx.account.id}`);
+  },
+}));
+
+await multi.login({
+  onCode(accountId, code) {
+    console.log(`[${accountId}] Código de pareamento:`, code);
+  },
+});
+```
+
+Quando `auth` não é informado na conta, o WhaNext cria automaticamente caminhos separados como `./sessions/principal`, `./sessions/secundaria` e `./sessions/terceira`. O mesmo diretório de sessão não pode ser usado por duas contas do provider padrão.
+
+Uma conta específica continua sendo um `WhaNextApp` completo:
+
+```ts
+const principal = multi.get('principal');
+
+if (principal?.isReady) {
+  await principal.message.send('5511999999999@s.whatsapp.net', {
+    text: 'Olá pela conta principal.',
+  });
+}
+```
+
+`multi.commands.command()`, `use()`, `onError()` e `load()` aplicam a mesma configuração de comandos a todas as contas. Dentro de um comando, `ctx.account.id` informa qual conta recebeu e executou aquela interação. Eventos também podem ser observados em conjunto com `multi.on()`.
+
 ## Logging
 
 O nível padrão é `info`. Estão disponíveis `debug`, `info`, `warn`, `error` e `silent`.
@@ -315,7 +373,21 @@ 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.
+`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:
+
+```ts
+if (message.quoted?.isViewOnce && message.quoted.hasMedia) {
+  const media = await app.media.download(message.quoted);
+
+  console.log(message.quoted.contentKind); // image | video | audio
+  console.log(message.quoted.media?.kind);
+  console.log(media.mimetype);
+}
+```
+
+Isso também funciona quando a mídia de visualização única aparece dentro de envelopes `viewOnceMessageV2` ou `viewOnceMessageV2Extension`.
 
 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`.
 
@@ -477,6 +549,56 @@ app.commands.command(
 );
 ```
 
+### Comandos exclusivos do dono
+
+O dono é a própria conta conectada naquela aplicação. Não é necessário salvar número, JID ou LID manualmente. O provider usa a marca de mensagem enviada pela própria conta e, quando necessário, compara as identidades normalizadas da sessão.
+
+```ts
+app.commands.command(defineCommand({
+  name: 'chay',
+  description: 'Comando privado da conta conectada.',
+  guards: [guards.owner()],
+
+  async execute(ctx) {
+    await ctx.reply('💣 *Comando autorizado*');
+  },
+}));
+```
+
+No contexto moderno também é possível consultar a informação diretamente:
+
+```ts
+if (ctx.isOwner) {
+  console.log(ctx.account.ids);
+}
+```
+
+A identidade da própria conta também pode ser consultada sem escolher manualmente entre JID e LID:
+
+```ts
+console.log(app.account.jid);         // 5531...@s.whatsapp.net
+console.log(app.account.lid);         // ...@lid
+console.log(app.account.phoneNumber); // 5531...
+console.log(app.account.selfChatId);  // destino preferencial para falar consigo mesmo
+```
+
+`selfChatId` prioriza o PN JID canônico e remove automaticamente sufixos de dispositivo como `:12@s.whatsapp.net`.
+
+Na API legada, use `onlyOwner: true`:
+
+```ts
+app.router().command(defineCommand({
+  name: 'interno',
+  description: 'Comando exclusivo do dono.',
+  onlyOwner: true,
+  execute(message) {
+    return app.message.reply(message, { text: 'Autorizado.' });
+  },
+}));
+```
+
+Em uma instância criada com `createMulti()`, o dono é resolvido separadamente para cada conta. Uma mensagem enviada pela conta `principal` não passa automaticamente como dona da conta `secundaria`.
+
 ### Subcomandos
 
 ```ts
@@ -579,6 +701,7 @@ Restrições disponíveis:
 - `onlyPrivate`
 - `onlyAdmin`
 - `botMustBeAdmin`
+- `onlyOwner`
 
 `ArgsParser` possui `string`, `number`, `boolean`, `enum`, `user`, `duration`, `peek`, `skip` e `rest`. `args.user()` retorna `User`, nunca uma string crua.
 

package/SECURITY.md

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

package/dist/index.d.ts

@@ -86,6 +86,15 @@ interface QuotedMessage {
     senderId?: string;
     sender?: User;
     hasMedia: boolean;
+    /**
+     * Indica se a mensagem citada foi enviada como visualização única.
+     * O provider oficial sempre preenche este campo.
+     */
+    isViewOnce?: boolean;
+    /** Classificação normalizada do conteúdo citado. */
+    contentKind?: MessageContentKind;
+    /** Metadados da mídia citada, quando houver. */
+    media?: MessageMedia;
 }
 interface Message {
     id: string;
@@ -129,9 +138,7 @@ type MediaSource = Uint8Array | {
     path: string;
 };
 type MentionTarget = string | User;
-/** Options for reposting a previously received message without quoting it. */
 interface RepostMessageOptions {
-    /** Hidden or visible mentions injected into the reposted payload. */
     mentions?: readonly MentionTarget[];
 }
 interface TextContent {
@@ -430,7 +437,7 @@ declare class MediaService {
     video(chatId: string, content: VideoContent): Promise<SentMessage>;
     audio(chatId: string, content: AudioContent): Promise<SentMessage>;
     sticker(chatId: string, content: StickerContent): Promise<SentMessage>;
-    download(message: Message | MessageKey): Promise<DownloadedMedia>;
+    download(message: Message | QuotedMessage | MessageKey): Promise<DownloadedMedia>;
 }
 
 declare class MemberService {
@@ -470,7 +477,13 @@ interface CommandCatalogView {
     has(path: string): boolean;
     find(path: string): RegisteredCommand | undefined;
 }
+interface CommandAccountContext {
+    readonly id: string | undefined;
+    readonly ids: readonly string[];
+    isOwner(message: Pick<Message, 'keys' | 'senderIds'>): boolean;
+}
 interface CommandRuntimeServices {
+    account: CommandAccountContext;
     messages: MessageService;
     media: MediaService;
     groups: GroupService;
@@ -495,6 +508,8 @@ interface ReplyOptions {
 interface CommandContext<Schema extends CommandOptionSchema = CommandOptionSchema> extends Message {
     readonly message: Message;
     readonly user: User;
+    readonly account: CommandAccountContext;
+    readonly isOwner: boolean;
     readonly chat: CommandChatContext;
     readonly group: CommandGroupContext | undefined;
     readonly command: RegisteredCommand;
@@ -548,6 +563,7 @@ interface GuardResult {
 }
 type CommandGuard = (context: CommandContext) => boolean | void | GuardResult | Promise<boolean | void | GuardResult>;
 declare const guards: {
+    owner(): CommandGuard;
     group(): CommandGuard;
     private(): CommandGuard;
     userAdmin(): CommandGuard;
@@ -596,6 +612,7 @@ interface CommandMetadata {
     onlyPrivate?: boolean;
     onlyAdmin?: boolean;
     botMustBeAdmin?: boolean;
+    onlyOwner?: boolean;
 }
 interface ExecutableCommandDefinition<Schema extends CommandOptionSchema = CommandOptionSchema> extends CommandMetadata {
     options?: Schema;
@@ -702,6 +719,18 @@ declare class Logger {
     error(message: string, context?: LogContext): void;
 }
 
+declare class AccountService {
+    #private;
+    readonly id: string | undefined;
+    constructor(provider: WhatsAppProvider, id?: string);
+    get ids(): readonly string[];
+    get jid(): string | undefined;
+    get lid(): string | undefined;
+    get phoneNumber(): string | undefined;
+    get selfChatId(): string | undefined;
+    isOwner(message: Pick<Message, 'keys' | 'senderIds'>): boolean;
+}
+
 interface AppEvents {
     message: Message;
     connection: ConnectionUpdate;
@@ -731,9 +760,11 @@ interface WhaNextAppOptions {
     logger?: LoggerConfig;
     mute?: MuteOptions;
     router?: Omit<RouterOptions, 'prefix'>;
+    accountId?: string;
 }
 declare class WhaNextApp {
     #private;
+    readonly account: AccountService;
     readonly message: MessageService;
     readonly media: MediaService;
     readonly group: GroupService;
@@ -777,9 +808,58 @@ interface CreateOptions {
     reconnect?: ReconnectOptions;
     messageCacheSize?: number;
     provider?: WhatsAppProvider;
+    accountId?: string;
 }
 declare function create(options?: CreateOptions): Promise<WhaNextApp>;
 
+interface MultiAccountOptions extends Omit<CreateOptions, 'accountId'> {
+    id: string;
+}
+interface CreateMultiOptions extends Omit<CreateOptions, 'accountId' | 'auth' | 'phone' | 'provider'> {
+    accounts: readonly MultiAccountOptions[];
+    authRoot?: string;
+}
+interface MultiLoginOptions extends Omit<LoginOptions, 'onCode'> {
+    onCode?: (accountId: string, code: string) => void | Promise<void>;
+}
+interface MultiAppHealth extends AppHealth {
+    accountId: string;
+}
+interface MultiAppEvent<Event extends keyof AppEvents> {
+    accountId: string;
+    app: WhaNextApp;
+    payload: AppEvents[Event];
+}
+interface MultiLoadCommandsResult {
+    accountId: string;
+    result: LoadCommandsResult;
+}
+declare class MultiCommandRouter {
+    #private;
+    constructor(apps: ReadonlyMap<string, WhaNextApp>);
+    command(definition: CommandDefinition): this;
+    use(middleware: CommandMiddleware): this;
+    onError(handler: CommandErrorHandler): () => void;
+    load(dirPath: string | URL, options?: LoadCommandsOptions): Promise<readonly MultiLoadCommandsResult[]>;
+}
+declare class WhaNextMultiApp {
+    #private;
+    readonly commands: MultiCommandRouter;
+    constructor(apps: ReadonlyMap<string, WhaNextApp>);
+    get size(): number;
+    get isReady(): boolean;
+    ids(): readonly string[];
+    has(accountId: string): boolean;
+    get(accountId: string): WhaNextApp | undefined;
+    values(): readonly WhaNextApp[];
+    router(): MultiCommandRouter;
+    on<Event extends keyof AppEvents>(event: Event, listener: (entry: MultiAppEvent<Event>) => void | Promise<void>): () => void;
+    health(): readonly MultiAppHealth[];
+    login(options?: MultiLoginOptions): Promise<void>;
+    disconnect(): Promise<void>;
+}
+declare function createMulti(options: CreateMultiOptions): Promise<WhaNextMultiApp>;
+
 interface MemoryCacheStats {
     size: number;
     maxEntries: number;
@@ -812,4 +892,4 @@ declare class SqliteMuteStore implements MuteStore {
     close(): void;
 }
 
-export { type AddMuteOptions, type AddMuteResult, type AppEvents, type AppHealth, type AppHealthStatus, ArgsParser, type AudioContent, type BooleanOption, Browser, type CacheOptions, type CacheStore, type CallEvent, type CallStatus, type ChangeResult, 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 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 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 MessageContent, type MessageContentKind, type MessageKey, type MessageMedia, 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, type WhatsAppProvider, create, 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 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 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 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 MessageContent, type MessageContentKind, 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 };