// WhatsApp Engine Interface - Abstract layer for WA engines export enum EngineStatus { DISCONNECTED = 'disconnected', INITIALIZING = 'initializing', QR_READY = 'qr_ready', AUTHENTICATING = 'authenticating', READY = 'ready', FAILED = 'failed', } export interface MessageResult { id: string; timestamp: number; ack?: number; } export interface MediaInput { mimetype: string; data: Buffer | string; // Buffer or base64 or URL filename?: string; caption?: string; } export interface IncomingMessage { id: string; from: string; to: string; chatId: string; body: string; type: string; timestamp: number; fromMe: boolean; isGroup: boolean; /** For group messages, the WID of the participant who actually sent it (`from` is the group JID there). */ author?: string; /** Sender display info, best-effort from the WhatsApp Web contact cache. */ contact?: { name?: string; pushName?: string; }; media?: { mimetype: string; filename?: string; data?: string; // base64 }; quotedMessage?: { id: string; body: string; }; location?: { latitude: number; longitude: number; description?: string; address?: string; url?: string; }; } export interface Contact { id: string; name?: string; pushName?: string; number: string; isMyContact: boolean; isBlocked: boolean; profilePicUrl?: string; } export interface Group { id: string; name: string; participantsCount?: number; isAdmin?: boolean; /** JID of the parent community this group is linked to, or null if standalone. */ linkedParentJID?: string | null; } export interface GroupParticipant { id: string; number: string; name?: string; isAdmin: boolean; isSuperAdmin: boolean; } export interface GroupInfo { id: string; name: string; description?: string; owner?: string; createdAt?: number; participants: GroupParticipant[]; isReadOnly?: boolean; isAnnounce?: boolean; /** JID of the parent community this group is linked to, or null if standalone. */ linkedParentJID?: string | null; } export interface ContactCard { name: string; number: string; } export interface LocationInput { latitude: number; longitude: number; description?: string; address?: string; } export interface ReactionSender { senderId: string; emoji: string; timestamp: number; } export interface MessageReaction { emoji: string; senders: ReactionSender[]; } // Phase 3: Labels (WhatsApp Business) export interface Label { id: string; name: string; hexColor: string; } // Phase 3: Status/Stories export interface Status { id: string; contact: { id: string; name?: string; pushName?: string; }; type: 'text' | 'image' | 'video'; caption?: string; mediaUrl?: string; backgroundColor?: string; font?: number; timestamp: Date; expiresAt: Date; } export interface TextStatusOptions { backgroundColor?: string; font?: number; } export interface StatusResult { statusId: string; timestamp: Date; expiresAt: Date; } // Phase 3: Channels/Newsletter export interface Channel { id: string; name: string; description?: string; inviteCode?: string; subscriberCount?: number; picture?: string; verified?: boolean; createdAt?: number; } export interface ChannelMessage { id: string; body: string; timestamp: number; hasMedia: boolean; mediaUrl?: string; } // Phase 3: Catalog (WhatsApp Business) export interface Catalog { id: string; name: string; description?: string; productCount: number; url: string; } export interface Product { id: string; name: string; description?: string; price: number; currency: string; priceFormatted: string; imageUrl?: string; url: string; isAvailable: boolean; retailerId?: string; } export interface ProductQueryOptions { page?: number; limit?: number; } export interface PaginatedProducts { products: Product[]; pagination: { page: number; limit: number; total: number; totalPages: number; }; } /** * Lightweight summary of a chat, exposed to the dashboard's real-time chats view. * Only library-agnostic primitives are leaked here; raw whatsapp-web.js objects are * mapped to this shape inside the adapter. */ export interface ChatSummary { id: string; name: string; isGroup: boolean; unreadCount: number; timestamp: number; lastMessage?: string; } /** * Structured payload for a remotely-revoked ("deleted for everyone") message. * The engine layer never emits a localized display string; `body` is intentionally * empty and the dashboard renders the localized "message deleted" text. */ export interface RevokedMessage { id: string; chatId: string; from: string; to: string; type: 'revoked'; body: ''; timestamp: number; } export interface ReactionEvent { messageId: string; chatId: string; reaction: string; senderId: string; } export interface EngineEventCallbacks { onQRCode?: (qr: string) => void; onReady?: (phone: string, pushName: string) => void; onMessage?: (message: IncomingMessage) => void; /** * Fired for messages the account itself created (outgoing) — including sends composed on a * linked phone, which the `message`/`onMessage` event never delivers. Used to emit `message.sent`. */ onMessageCreate?: (message: IncomingMessage) => void; onMessageAck?: (messageId: string, ack: number) => void; onMessageRevoked?: (message: RevokedMessage) => void; onMessageReaction?: (event: ReactionEvent) => void; onDisconnected?: (reason: string) => void; onStateChanged?: (state: EngineStatus) => void; /** * Fired on a terminal initialization/authentication failure (e.g. Chromium * could not launch, or WhatsApp rejected the stored credentials). The engine * has already moved to FAILED; `reason` carries a human-readable cause that * callers may surface to operators. Distinct from `onDisconnected`, which is * recoverable and triggers reconnection. */ onError?: (reason: string) => void; } export interface IWhatsAppEngine { // Lifecycle initialize(callbacks: EngineEventCallbacks): Promise; disconnect(): Promise; // Closes browser but keeps session (can reconnect without QR) logout(): Promise; // Logs out and clears session data (requires QR scan again) destroy(): Promise; // Status getStatus(): EngineStatus; getQRCode(): string | null; getPhoneNumber(): string | null; getPushName(): string | null; // Messaging - Basic sendTextMessage(chatId: string, text: string): Promise; sendImageMessage(chatId: string, media: MediaInput): Promise; sendVideoMessage(chatId: string, media: MediaInput): Promise; sendAudioMessage(chatId: string, media: MediaInput): Promise; sendDocumentMessage(chatId: string, media: MediaInput): Promise; // Messaging - Extended (Phase 3) sendLocationMessage(chatId: string, location: LocationInput): Promise; sendContactMessage(chatId: string, contact: ContactCard): Promise; sendStickerMessage(chatId: string, media: MediaInput): Promise; // Reply & Forward replyToMessage(chatId: string, quotedMsgId: string, text: string): Promise; forwardMessage(fromChatId: string, toChatId: string, messageId: string): Promise; // Reactions (Phase 3) reactToMessage(chatId: string, messageId: string, emoji: string): Promise; getMessageReactions(chatId: string, messageId: string): Promise; // Contacts getContacts(): Promise; getContactById(contactId: string): Promise; checkNumberExists(number: string): Promise; // Groups - Basic getGroups(): Promise; // Groups - Extended (Phase 3) getGroupInfo(groupId: string): Promise; createGroup(name: string, participants: string[]): Promise; addParticipants(groupId: string, participants: string[]): Promise; removeParticipants(groupId: string, participants: string[]): Promise; promoteParticipants(groupId: string, participants: string[]): Promise; demoteParticipants(groupId: string, participants: string[]): Promise; leaveGroup(groupId: string): Promise; setGroupSubject(groupId: string, subject: string): Promise; setGroupDescription(groupId: string, description: string): Promise; getGroupInviteCode(groupId: string): Promise; revokeGroupInviteCode(groupId: string): Promise; // Message Operations deleteMessage(chatId: string, messageId: string, forEveryone?: boolean): Promise; getChatHistory(chatId: string, limit?: number, includeMedia?: boolean): Promise; // Contact Extended Operations getProfilePicture(contactId: string): Promise; blockContact(contactId: string): Promise; unblockContact(contactId: string): Promise; // Labels (Phase 3) - WhatsApp Business only getLabels(): Promise; getLabelById(labelId: string): Promise