@whanext/core 0.8.0 → 0.11.0

package/dist/index.d.ts

@@ -147,33 +147,6 @@ interface StickerContent {
 }
 type MessageContent = TextContent | ImageContent | VideoContent | AudioContent | StickerContent;
 
-interface CommandDefinition {
-    name: string;
-    description: string;
-    aliases?: readonly string[];
-    onlyGroup?: boolean;
-    onlyPrivate?: boolean;
-    onlyAdmin?: boolean;
-    botMustBeAdmin?: boolean;
-    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' | '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>>;
-    recoverable?: boolean;
-}
-declare class WhaNextError extends Error {
-    readonly code: WhaNextErrorCode;
-    readonly context: Readonly<Record<string, unknown>>;
-    readonly recoverable: boolean;
-    constructor(code: WhaNextErrorCode, message: string, options?: WhaNextErrorOptions);
-}
-declare function toWhaNextError(error: unknown, context?: Readonly<Record<string, unknown>>): WhaNextError;
-
 type GroupAccess = 'open' | 'closed';
 type GroupRole = 'member' | 'admin' | 'owner';
 type GroupAddressingMode = 'lid' | 'pn';
@@ -286,47 +259,75 @@ declare class GroupService {
     invalidate(groupId: string): Promise<void>;
 }
 
-interface RouterOptions {
-    prefix?: string;
-    onError?: (error: WhaNextError, message: Message) => void | Promise<void>;
-}
-declare class CommandRouter {
+declare class UserService {
     #private;
-    constructor(group: GroupService, options?: RouterOptions);
-    command(definition: CommandDefinition): this;
-    dispatch(message: Message): Promise<boolean>;
+    constructor(group: GroupService);
+    resolve(message: Message, args: ArgsParser): Promise<User>;
+    from(identity: string): User;
 }
 
-type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
-type LogFormat = 'pretty' | 'json';
-type LogContext = Readonly<Record<string, unknown>>;
-interface LogEntry {
-    timestamp: string;
-    level: Exclude<LogLevel, 'silent'>;
-    scope: string;
-    message: string;
-    context: LogContext;
+interface BaseOption<TKind extends string> {
+    kind: TKind;
+    description: string;
+    required?: boolean;
 }
-type LogWriter = (entry: LogEntry) => unknown;
-interface LoggerOptions {
-    level?: LogLevel;
-    format?: LogFormat;
-    writer?: LogWriter;
-    scope?: string;
-    redact?: readonly string[];
+interface StringOption extends BaseOption<'string'> {
+    rest?: boolean;
+    minLength?: number;
+    maxLength?: number;
 }
-type LoggerConfig = LogLevel | LoggerOptions;
-declare class Logger {
+interface NumberOption extends BaseOption<'number'> {
+    min?: number;
+    max?: number;
+}
+interface BooleanOption extends BaseOption<'boolean'> {
+}
+interface UserOption extends BaseOption<'user'> {
+}
+interface DurationOption extends BaseOption<'duration'> {
+}
+interface EnumOption<Values extends readonly string[] = readonly string[]> extends BaseOption<'enum'> {
+    values: Values;
+}
+type CommandOptionDefinition = StringOption | NumberOption | BooleanOption | UserOption | DurationOption | EnumOption;
+type CommandOptionSchema = Readonly<Record<string, CommandOptionDefinition>>;
+type RawOptionValue<Definition extends CommandOptionDefinition> = Definition extends StringOption ? string : Definition extends NumberOption ? number : Definition extends BooleanOption ? boolean : Definition extends UserOption ? User : Definition extends DurationOption ? number | undefined : Definition extends EnumOption<infer Values> ? Values[number] : never;
+type CommandOptionValue<Definition extends CommandOptionDefinition> = Definition['required'] extends true ? RawOptionValue<Definition> : RawOptionValue<Definition> | undefined;
+type CommandOptionValues<Schema extends CommandOptionSchema> = {
+    readonly [Name in keyof Schema]: CommandOptionValue<Schema[Name]>;
+};
+declare const option: {
+    string<const Definition extends Omit<StringOption, "kind">>(definition: Definition): {
+        kind: "string";
+    } & Definition;
+    number<const Definition extends Omit<NumberOption, "kind">>(definition: Definition): {
+        kind: "number";
+    } & Definition;
+    boolean<const Definition extends Omit<BooleanOption, "kind">>(definition: Definition): {
+        kind: "boolean";
+    } & Definition;
+    user<const Definition extends Omit<UserOption, "kind">>(definition: Definition): {
+        kind: "user";
+    } & Definition;
+    duration<const Definition extends Omit<DurationOption, "kind">>(definition: Definition): {
+        kind: "duration";
+    } & Definition;
+    enum<const Values extends readonly string[], const Definition extends Omit<EnumOption<Values>, "kind" | "values">>(values: Values, definition: Definition): {
+        kind: "enum";
+        values: Values;
+    } & Definition;
+};
+declare class ParsedCommandOptions<Schema extends CommandOptionSchema = CommandOptionSchema> {
     #private;
-    constructor(config?: LoggerConfig);
-    get level(): LogLevel;
-    setLevel(level: LogLevel): this;
-    isEnabled(level: Exclude<LogLevel, 'silent'>): boolean;
-    child(scope: string): Logger;
-    debug(message: string, context?: LogContext): void;
-    info(message: string, context?: LogContext): void;
-    warn(message: string, context?: LogContext): void;
-    error(message: string, context?: LogContext): void;
+    constructor(values: CommandOptionValues<Schema>);
+    get<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    string<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    number<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    boolean<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    user<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    duration<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    enum<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    toJSON(): CommandOptionValues<Schema>;
 }
 
 interface StoredMute {
@@ -437,11 +438,247 @@ declare class MessageService {
     text(chatId: string, text: string, mentions?: MentionTarget[]): Promise<SentMessage>;
 }
 
-declare class UserService {
+interface CommandCatalogView {
+    readonly prefix: string;
+    readonly size: number;
+    catalog(options?: {
+        category?: string;
+        includeHidden?: boolean;
+    }): readonly RegisteredCommand[];
+    categories(): readonly string[];
+    has(path: string): boolean;
+    find(path: string): RegisteredCommand | undefined;
+}
+interface CommandRuntimeServices {
+    messages: MessageService;
+    media: MediaService;
+    groups: GroupService;
+    members: MemberService;
+    chats: ChatService;
+    users: UserService;
+    mute: MuteService;
+}
+interface CommandChatContext {
+    id: string;
+    isGroup: boolean;
+}
+interface CommandGroupContext {
+    id: string;
+    metadata(refresh?: boolean): ReturnType<GroupService['metadata']>;
+    isUserAdmin(): Promise<boolean>;
+    isBotAdmin(): Promise<boolean>;
+}
+interface ReplyOptions {
+    deleteAfterMs?: number;
+}
+interface CommandContext<Schema extends CommandOptionSchema = CommandOptionSchema> extends Message {
+    readonly message: Message;
+    readonly user: User;
+    readonly chat: CommandChatContext;
+    readonly group: CommandGroupContext | undefined;
+    readonly command: RegisteredCommand;
+    readonly commands: CommandCatalogView;
+    readonly prefix: string;
+    readonly options: ParsedCommandOptions<Schema>;
+    readonly args: ArgsParser;
+    readonly locale: string | undefined;
+    readonly signal: AbortSignal;
+    readonly client: CommandRuntimeServices;
+    readonly messages: MessageService;
+    readonly mediaService: MediaService;
+    readonly groups: GroupService;
+    readonly members: MemberService;
+    readonly chats: ChatService;
+    readonly users: UserService;
+    readonly muteService: MuteService;
+    reply(content: string | MessageContent, options?: ReplyOptions): Promise<SentMessage>;
+    defer(content?: string | MessageContent): Promise<DeferredReply>;
+    edit(content: string): Promise<SentMessage>;
+    react(emoji: string): Promise<SentMessage>;
+    unreact(): Promise<SentMessage>;
+    delete(): Promise<void>;
+    deleteReply(options?: ReplyOptions): Promise<void>;
+}
+declare class DeferredReply {
     #private;
-    constructor(group: GroupService);
-    resolve(message: Message, args: ArgsParser): Promise<User>;
-    from(identity: string): User;
+    constructor(messages: MessageService, message: SentMessage, onEdit: (message: SentMessage) => void);
+    edit(content: string): Promise<SentMessage>;
+    delete(): Promise<void>;
+}
+
+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_COOLDOWN' | 'COMMAND_BUSY' | 'COMMAND_LOAD_FAILED' | 'PROVIDER_ERROR' | 'UNKNOWN_ERROR';
+interface WhaNextErrorOptions {
+    cause?: unknown;
+    context?: Readonly<Record<string, unknown>>;
+    recoverable?: boolean;
+}
+declare class WhaNextError extends Error {
+    readonly code: WhaNextErrorCode;
+    readonly context: Readonly<Record<string, unknown>>;
+    readonly recoverable: boolean;
+    constructor(code: WhaNextErrorCode, message: string, options?: WhaNextErrorOptions);
+}
+declare function toWhaNextError(error: unknown, context?: Readonly<Record<string, unknown>>): WhaNextError;
+
+interface GuardResult {
+    allowed: boolean;
+    code?: WhaNextErrorCode;
+    message?: string;
+}
+type CommandGuard = (context: CommandContext) => boolean | void | GuardResult | Promise<boolean | void | GuardResult>;
+declare const guards: {
+    group(): CommandGuard;
+    private(): CommandGuard;
+    userAdmin(): CommandGuard;
+    botAdmin(): CommandGuard;
+    botEnabled(check: (context: CommandContext) => boolean | Promise<boolean>): CommandGuard;
+    custom(guard: CommandGuard): CommandGuard;
+};
+
+type CommandScope = 'global' | 'user' | 'chat' | 'user-chat' | 'user-group';
+type ConcurrencyStrategy = 'parallel' | 'reject' | 'queue' | 'replace';
+interface CommandCooldown {
+    durationMs: number;
+    scope?: CommandScope;
+}
+interface CommandConcurrency {
+    max?: number;
+    scope?: CommandScope;
+    strategy?: ConcurrencyStrategy;
+}
+interface CommandLocalization {
+    name?: string;
+    aliases?: readonly string[];
+    description?: string;
+}
+type CommandMiddleware = (context: CommandContext, next: () => Promise<void>) => void | Promise<void>;
+interface CommandHooks {
+    beforeExecute?: (context: CommandContext) => void | Promise<void>;
+    afterExecute?: (context: CommandContext) => void | Promise<void>;
+    onError?: (context: CommandContext, error: Error) => void | Promise<void>;
+}
+interface CommandMetadata {
+    name: string;
+    description: string;
+    aliases?: readonly string[];
+    category?: string;
+    usage?: string;
+    examples?: readonly string[];
+    hidden?: boolean;
+    localizations?: Readonly<Record<string, CommandLocalization>>;
+    guards?: readonly CommandGuard[];
+    middleware?: readonly CommandMiddleware[];
+    cooldown?: CommandCooldown;
+    concurrency?: CommandConcurrency;
+    hooks?: CommandHooks;
+    onlyGroup?: boolean;
+    onlyPrivate?: boolean;
+    onlyAdmin?: boolean;
+    botMustBeAdmin?: boolean;
+}
+interface ExecutableCommandDefinition<Schema extends CommandOptionSchema = CommandOptionSchema> extends CommandMetadata {
+    options?: Schema;
+    execute(context: CommandContext<Schema>, args: ArgsParser): void | Promise<void>;
+}
+interface CommandGroupDefinition extends CommandMetadata {
+    subcommands: readonly CommandDefinition[];
+}
+type CommandDefinition<Schema extends CommandOptionSchema = CommandOptionSchema> = ExecutableCommandDefinition<Schema> | CommandGroupDefinition;
+interface RegisteredCommand {
+    definition: ExecutableCommandDefinition;
+    root: CommandDefinition;
+    path: readonly string[];
+    aliases: readonly string[];
+    category: string;
+}
+declare function defineCommand<const Schema extends CommandOptionSchema = CommandOptionSchema>(command: ExecutableCommandDefinition<Schema>): ExecutableCommandDefinition<Schema>;
+declare function defineSubcommand<const Schema extends CommandOptionSchema = CommandOptionSchema>(command: ExecutableCommandDefinition<Schema>): ExecutableCommandDefinition<Schema>;
+declare function defineCommandGroup<const Group extends CommandGroupDefinition>(group: Group): Group;
+declare function defineCommands<const Commands extends readonly CommandDefinition[]>(...commands: Commands): Commands;
+declare function isCommandGroup(definition: CommandDefinition): definition is CommandGroupDefinition;
+
+interface CommandRegistrar {
+    command(definition: CommandDefinition): unknown;
+}
+interface LoadCommandsOptions {
+    extensions?: readonly string[];
+    recursive?: boolean;
+}
+interface LoadCommandsResult {
+    loaded: readonly string[];
+    skipped: readonly string[];
+    commands: readonly LoadedCommand[];
+}
+interface LoadedCommand {
+    name: string;
+    filePath: string;
+}
+declare function loadCommands(registrar: CommandRegistrar, dirPath: string | URL, options?: LoadCommandsOptions): Promise<LoadCommandsResult>;
+
+interface RouterOptions {
+    prefix?: string;
+    onError?: (error: WhaNextError, message: Message) => void | Promise<void>;
+    onCommandError?: CommandErrorHandler;
+    beforeExecute?: (context: CommandContext) => void | Promise<void>;
+    afterExecute?: (context: CommandContext) => void | Promise<void>;
+}
+interface CommandCatalogOptions {
+    category?: string;
+    includeHidden?: boolean;
+}
+interface CommandHelpOptions extends CommandCatalogOptions {
+    title?: string;
+}
+type CommandErrorHandler = (context: CommandContext, error: WhaNextError) => void | Promise<void>;
+declare class CommandRouter {
+    #private;
+    constructor(services: CommandRuntimeServices, options?: RouterOptions);
+    constructor(group: GroupService, options?: RouterOptions);
+    get prefix(): string;
+    get size(): number;
+    command(definition: CommandDefinition): this;
+    load(dirPath: string | URL, options?: LoadCommandsOptions): Promise<LoadCommandsResult>;
+    use(middleware: CommandMiddleware): this;
+    onError(handler: CommandErrorHandler): () => void;
+    catalog(options?: CommandCatalogOptions): readonly RegisteredCommand[];
+    categories(): readonly string[];
+    has(path: string): boolean;
+    values(): readonly RegisteredCommand[];
+    find(path: string): RegisteredCommand | undefined;
+    help(context: CommandContext, options?: CommandHelpOptions): Promise<SentMessage>;
+    dispatch(message: Message): Promise<boolean>;
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+type LogFormat = 'pretty' | 'json';
+type LogContext = Readonly<Record<string, unknown>>;
+interface LogEntry {
+    timestamp: string;
+    level: Exclude<LogLevel, 'silent'>;
+    scope: string;
+    message: string;
+    context: LogContext;
+}
+type LogWriter = (entry: LogEntry) => unknown;
+interface LoggerOptions {
+    level?: LogLevel;
+    format?: LogFormat;
+    writer?: LogWriter;
+    scope?: string;
+    redact?: readonly string[];
+}
+type LoggerConfig = LogLevel | LoggerOptions;
+declare class Logger {
+    #private;
+    constructor(config?: LoggerConfig);
+    get level(): LogLevel;
+    setLevel(level: LogLevel): this;
+    isEnabled(level: Exclude<LogLevel, 'silent'>): boolean;
+    child(scope: string): Logger;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext): void;
 }
 
 interface AppEvents {
@@ -484,6 +721,7 @@ declare class WhaNextApp {
     readonly user: UserService;
     readonly mute: MuteService;
     readonly logger: Logger;
+    readonly commands: CommandRouter;
     constructor(provider: WhatsAppProvider, options?: WhaNextAppOptions, logger?: Logger);
     get state(): ConnectionUpdate['state'];
     get isReady(): boolean;
@@ -521,6 +759,15 @@ interface CreateOptions {
 }
 declare function create(options?: CreateOptions): Promise<WhaNextApp>;
 
+interface MemoryCacheStats {
+    size: number;
+    maxEntries: number;
+    hits: number;
+    misses: number;
+    sets: number;
+    evictions: number;
+    expirations: number;
+}
 declare class MemoryCache implements CacheStore {
     #private;
     constructor(options?: {
@@ -530,26 +777,10 @@ declare class MemoryCache implements CacheStore {
     set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
     delete(key: string): Promise<void>;
     clear(): Promise<void>;
+    prune(now?: number): number;
+    stats(): Readonly<MemoryCacheStats>;
 }
 
-interface CommandRegistrar {
-    command(definition: CommandDefinition): unknown;
-}
-interface LoadCommandsOptions {
-    extensions?: readonly string[];
-    recursive?: boolean;
-}
-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>;
-
 declare class SqliteMuteStore implements MuteStore {
     #private;
     constructor(path?: string);
@@ -560,4 +791,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 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 StickerContent, type StoredMute, type TextContent, User, type UserData, type VideoContent, WhaNextApp, WhaNextError, type WhaNextErrorCode, type WhatsAppProvider, create, defineCommand, defineCommands, loadCommands, toWhaNextError };
+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 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 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 };