@whanext/core 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,500 @@
+interface CacheStore {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+interface CacheOptions {
+    store?: CacheStore;
+    groupTtlMs?: number;
+}
+
+interface UserData {
+    id: string;
+    identities?: readonly string[];
+    jid?: string;
+    lid?: string;
+    phoneNumber?: string;
+    name?: string;
+}
+declare class User {
+    readonly id: string;
+    readonly identities: string[];
+    readonly jid: string | undefined;
+    readonly lid: string | undefined;
+    readonly phoneNumber: string | undefined;
+    readonly name: string | undefined;
+    constructor(data: UserData);
+    get mentionId(): string;
+    get mention(): string;
+    get phone(): string | undefined;
+    get username(): string;
+    get displayName(): string;
+    matches(identity: string | User): boolean;
+    toJSON(): UserData;
+    static fromIdentities(identities: readonly string[]): User;
+    static fromPhoneNumber(phoneNumber: string): User;
+}
+
+interface ArgumentOptions {
+    optional?: boolean;
+}
+declare class ArgsParser {
+    #private;
+    constructor(values: readonly string[]);
+    get remaining(): number;
+    peek(): string | undefined;
+    skip(count?: number): this;
+    string(name?: string, options?: ArgumentOptions): string | undefined;
+    number(name?: string, options?: ArgumentOptions): number | undefined;
+    boolean(name?: string, options?: ArgumentOptions): boolean | undefined;
+    enum<const Values extends readonly string[]>(values: Values, name?: string, options?: ArgumentOptions): Values[number] | undefined;
+    user(name?: string): User;
+    user(name: string, options: {
+        optional: true;
+    }): User | undefined;
+    duration(name?: string, options?: ArgumentOptions): number | undefined;
+    rest(): string;
+}
+
+interface MessageKey {
+    id: string;
+    chatId: string;
+    fromMe: boolean;
+    participantId?: string;
+}
+type MediaKind = 'image' | 'video' | 'audio' | 'document' | 'sticker';
+interface MessageMedia {
+    kind: MediaKind;
+    mimetype?: string;
+    fileName?: string;
+    seconds?: number;
+    viewOnce: boolean;
+}
+interface QuotedMessage {
+    key: MessageKey;
+    text?: string;
+    senderId?: string;
+    sender?: User;
+    hasMedia: boolean;
+}
+interface Message {
+    id: string;
+    jid: string;
+    lid?: string;
+    chatId: string;
+    senderId: string;
+    senderIds: string[];
+    senderJid?: string;
+    senderLid?: string;
+    sender: User;
+    keys: MessageKey;
+    text?: string;
+    caption?: string;
+    mentions: string[];
+    mentionedUsers: User[];
+    timestamp: Date;
+    isGroup: boolean;
+    isReply: boolean;
+    isViewOnce: boolean;
+    hasMedia: boolean;
+    media?: MessageMedia;
+    quoted?: QuotedMessage;
+}
+interface SentMessage {
+    id: string;
+    chatId: string;
+    keys: MessageKey;
+    timestamp: Date;
+}
+type MediaSource = Uint8Array | {
+    url: string;
+} | {
+    path: string;
+};
+type MentionTarget = string | User;
+interface TextContent {
+    text: string;
+    mentions?: MentionTarget[];
+}
+interface ImageContent {
+    image: MediaSource;
+    caption?: string;
+    mentions?: MentionTarget[];
+    viewOnce?: boolean;
+}
+interface VideoContent {
+    video: MediaSource;
+    caption?: string;
+    mentions?: MentionTarget[];
+    viewOnce?: boolean;
+    gif?: boolean;
+}
+interface AudioContent {
+    audio: MediaSource;
+    mimetype?: string;
+    voice?: boolean;
+}
+type MessageContent = TextContent | ImageContent | VideoContent | AudioContent;
+
+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;
+
+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' | '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';
+interface GroupParticipant {
+    id: string;
+    lid?: string;
+    phoneNumber?: string;
+    role: GroupRole;
+}
+interface GroupSnapshot {
+    id: string;
+    subject: string;
+    access: GroupAccess;
+    addressingMode: GroupAddressingMode;
+    participants: GroupParticipant[];
+    fetchedAt: Date;
+}
+type ChangeResult<State extends string> = {
+    ok: true;
+    changed: true;
+    state: State;
+} | {
+    ok: true;
+    changed: false;
+    state: State;
+};
+interface InviteResult {
+    ok: true;
+    url: string;
+    code: string;
+}
+type MemberAction = 'removed' | 'promoted' | 'demoted';
+type MemberActionState = MemberAction | 'already_removed' | 'already_admin' | 'not_admin' | 'not_in_group';
+
+type ConnectionState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
+type PresenceState = 'typing' | 'recording' | 'paused';
+type ParticipantAction = 'remove' | 'promote' | 'demote';
+interface ParticipantUpdateResult {
+    success: boolean;
+    status: string;
+    memberId?: string;
+}
+interface ConnectionUpdate {
+    state: ConnectionState;
+    attempt?: number;
+    error?: Error;
+}
+interface ProviderEvents {
+    message: Message;
+    connection: ConnectionUpdate;
+    groupChanged: {
+        groupId: string;
+    };
+}
+type Unsubscribe = () => void;
+interface WhatsAppProvider {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getCurrentUserIds(): string[];
+    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>;
+    editMessage(key: MessageKey, content: string): Promise<SentMessage>;
+    deleteMessage(key: MessageKey): Promise<void>;
+    getGroup(groupId: string): Promise<GroupSnapshot>;
+    setGroupAccess(groupId: string, access: GroupAccess): Promise<void>;
+    getGroupInviteCode(groupId: string): Promise<string>;
+    revokeGroupInvite(groupId: string): Promise<string>;
+    setMessagePin(groupId: string, key: MessageKey, pinned: boolean): Promise<void>;
+    updateParticipant(groupId: string, memberId: string, action: ParticipantAction): Promise<ParticipantUpdateResult>;
+    setPresence(chatId: string, state: PresenceState): Promise<void>;
+}
+
+declare class GroupService {
+    #private;
+    constructor(provider: WhatsAppProvider, cache: CacheStore, ttlMs?: number);
+    open(groupId: string): Promise<ChangeResult<'open' | 'already_open'>>;
+    close(groupId: string): Promise<ChangeResult<'closed' | 'already_closed'>>;
+    invite(groupId: string): Promise<InviteResult>;
+    revokeInvite(groupId: string): Promise<InviteResult>;
+    pin(groupId: string, key: MessageKey): Promise<ChangeResult<'pinned'>>;
+    unpin(groupId: string, key: MessageKey): Promise<ChangeResult<'unpinned'>>;
+    metadata(groupId: string, refresh?: boolean): Promise<GroupSnapshot>;
+    isAdmin(groupId: string, memberIds: string | readonly string[]): Promise<boolean>;
+    isCurrentUserAdmin(groupId: string): Promise<boolean>;
+    resolveUser(groupId: string, user: User): Promise<User>;
+    invalidate(groupId: string): Promise<void>;
+}
+
+interface RouterOptions {
+    prefix?: string;
+    onError?: (error: WhaNextError, message: Message) => void | Promise<void>;
+}
+declare class CommandRouter {
+    #private;
+    constructor(group: GroupService, options?: RouterOptions);
+    command(definition: CommandDefinition): this;
+    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 StoredMute {
+    key: string;
+    groupId: string;
+    user: UserData;
+    identities: string[];
+    createdAt: number;
+    expiresAt: number | null;
+}
+interface MuteStore {
+    upsert(mute: StoredMute): void | Promise<void>;
+    find(groupId: string, identities: readonly string[]): StoredMute | undefined | Promise<StoredMute | undefined>;
+    delete(groupId: string, identities: readonly string[]): boolean | Promise<boolean>;
+    purgeExpired(now: number): number | Promise<number>;
+    close?(): void | Promise<void>;
+}
+interface MuteOptions {
+    enabled?: boolean;
+    store?: MuteStore;
+    database?: string;
+}
+
+interface AddMuteOptions {
+    durationMs?: number;
+}
+interface MuteRecord {
+    groupId: string;
+    user: User;
+    createdAt: Date;
+    expiresAt: Date | null;
+}
+type AddMuteResult = {
+    ok: true;
+    changed: true;
+    state: 'muted' | 'updated';
+    record: MuteRecord;
+} | {
+    ok: true;
+    changed: false;
+    state: 'already_muted';
+    record: MuteRecord;
+};
+type RemoveMuteResult = {
+    ok: true;
+    changed: true;
+    state: 'unmuted';
+} | {
+    ok: true;
+    changed: false;
+    state: 'already_unmuted';
+};
+type MuteChangeResult = AddMuteResult | RemoveMuteResult;
+interface MuteEnforcement {
+    message: Message;
+    record: MuteRecord;
+}
+declare class MuteService {
+    #private;
+    constructor(provider: WhatsAppProvider, store?: MuteStore);
+    get enabled(): boolean;
+    add(groupId: string, user: User, options?: AddMuteOptions): Promise<AddMuteResult>;
+    remove(groupId: string, user: User): Promise<RemoveMuteResult>;
+    get(groupId: string, user: User): Promise<MuteRecord | undefined>;
+    isMuted(groupId: string, user: User): Promise<boolean>;
+    enforce(message: Message): Promise<MuteEnforcement | undefined>;
+    purgeExpired(): Promise<number>;
+    close(): Promise<void>;
+}
+
+declare class ChatService {
+    #private;
+    constructor(provider: WhatsAppProvider);
+    typing(chatId: string): Promise<void>;
+    recording(chatId: string): Promise<void>;
+    stop(chatId: string): Promise<void>;
+    stopTyping(chatId: string): Promise<void>;
+}
+
+declare class MediaService {
+    #private;
+    constructor(provider: WhatsAppProvider);
+    image(chatId: string, content: ImageContent): Promise<SentMessage>;
+    video(chatId: string, content: VideoContent): Promise<SentMessage>;
+    audio(chatId: string, content: AudioContent): Promise<SentMessage>;
+}
+
+declare class MemberService {
+    #private;
+    constructor(provider: WhatsAppProvider, group: GroupService);
+    remove(groupId: string, member: string | User): Promise<ChangeResult<MemberActionState>>;
+    promote(groupId: string, member: string | User): Promise<ChangeResult<MemberActionState>>;
+    demote(groupId: string, member: string | User): Promise<ChangeResult<MemberActionState>>;
+}
+
+declare class MessageService {
+    #private;
+    constructor(provider: WhatsAppProvider);
+    send(chatId: string, content: MessageContent): Promise<SentMessage>;
+    reply(message: Message, content: MessageContent): Promise<SentMessage>;
+    edit(message: Message | SentMessage | MessageKey, text: string): Promise<SentMessage>;
+    delete(message: Message | SentMessage | MessageKey): Promise<void>;
+    text(chatId: string, text: string, mentions?: MentionTarget[]): Promise<SentMessage>;
+}
+
+declare class UserService {
+    #private;
+    constructor(group: GroupService);
+    resolve(message: Message, args: ArgsParser): Promise<User>;
+    from(identity: string): User;
+}
+
+interface AppEvents {
+    message: Message;
+    connection: ConnectionUpdate;
+    error: WhaNextError;
+    mute: MuteEnforcement;
+}
+interface LoginOptions {
+    onCode?: (code: string) => void | Promise<void>;
+    timeoutMs?: number;
+}
+type AppHealthStatus = 'idle' | 'starting' | 'ready' | 'stopped';
+interface AppHealth {
+    status: AppHealthStatus;
+    state: ConnectionUpdate['state'];
+    ready: boolean;
+    uptimeMs: number;
+    timestamp: Date;
+    muteEnabled: boolean;
+    logLevel: LogLevel;
+}
+interface WhaNextAppOptions {
+    phone?: string;
+    prefix?: string;
+    cache?: CacheOptions;
+    logger?: LoggerConfig;
+    mute?: MuteOptions;
+    router?: Omit<RouterOptions, 'prefix'>;
+}
+declare class WhaNextApp {
+    #private;
+    readonly message: MessageService;
+    readonly media: MediaService;
+    readonly group: GroupService;
+    readonly member: MemberService;
+    readonly chat: ChatService;
+    readonly user: UserService;
+    readonly mute: MuteService;
+    readonly logger: Logger;
+    constructor(provider: WhatsAppProvider, options?: WhaNextAppOptions, logger?: Logger);
+    get state(): ConnectionUpdate['state'];
+    get isReady(): boolean;
+    health(): AppHealth;
+    router(): CommandRouter;
+    on<Event extends keyof AppEvents>(event: Event, listener: (payload: AppEvents[Event]) => void | Promise<void>): () => void;
+    login(options?: LoginOptions): Promise<void>;
+    disconnect(): Promise<void>;
+}
+
+declare enum Browser {
+    Windows = "windows",
+    MacOS = "macos",
+    Ubuntu = "ubuntu"
+}
+
+interface ReconnectOptions {
+    enabled?: boolean;
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+}
+interface CreateOptions {
+    phone?: string;
+    browser?: Browser;
+    auth?: string;
+    prefix?: string;
+    cache?: CacheOptions;
+    logger?: LoggerConfig;
+    mute?: MuteOptions;
+    router?: Omit<RouterOptions, 'prefix'>;
+    reconnect?: ReconnectOptions;
+    provider?: WhatsAppProvider;
+}
+declare function create(options?: CreateOptions): Promise<WhaNextApp>;
+
+declare class MemoryCache implements CacheStore {
+    #private;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+declare class SqliteMuteStore implements MuteStore {
+    #private;
+    constructor(path?: string);
+    upsert(mute: StoredMute): void;
+    find(groupId: string, identities: readonly string[]): StoredMute | undefined;
+    delete(groupId: string, identities: readonly string[]): boolean;
+    purgeExpired(now: number): number;
+    close(): void;
+}
+
+export { type AddMuteOptions, type AddMuteResult, type AppEvents, type AppHealth, type AppHealthStatus, ArgsParser, type AudioContent, Browser, type CacheOptions, type CacheStore, type ChangeResult, type CommandDefinition, CommandRouter, type ConnectionState, type ConnectionUpdate, type CreateOptions, type GroupAccess, type GroupAddressingMode, type GroupParticipant, type GroupRole, type GroupSnapshot, type ImageContent, type InviteResult, 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, toWhaNextError };