openWa / src /engine /interfaces /whatsapp-engine.interface.ts
harsh
Deploy: Initial commit without binaries
525d39f
Raw History Blame Contribute Delete
10.6 kB
// 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<void>;
disconnect(): Promise<void>; // Closes browser but keeps session (can reconnect without QR)
logout(): Promise<void>; // Logs out and clears session data (requires QR scan again)
destroy(): Promise<void>;
// Status
getStatus(): EngineStatus;
getQRCode(): string | null;
getPhoneNumber(): string | null;
getPushName(): string | null;
// Messaging - Basic
sendTextMessage(chatId: string, text: string): Promise<MessageResult>;
sendImageMessage(chatId: string, media: MediaInput): Promise<MessageResult>;
sendVideoMessage(chatId: string, media: MediaInput): Promise<MessageResult>;
sendAudioMessage(chatId: string, media: MediaInput): Promise<MessageResult>;
sendDocumentMessage(chatId: string, media: MediaInput): Promise<MessageResult>;
// Messaging - Extended (Phase 3)
sendLocationMessage(chatId: string, location: LocationInput): Promise<MessageResult>;
sendContactMessage(chatId: string, contact: ContactCard): Promise<MessageResult>;
sendStickerMessage(chatId: string, media: MediaInput): Promise<MessageResult>;
// Reply & Forward
replyToMessage(chatId: string, quotedMsgId: string, text: string): Promise<MessageResult>;
forwardMessage(fromChatId: string, toChatId: string, messageId: string): Promise<MessageResult>;
// Reactions (Phase 3)
reactToMessage(chatId: string, messageId: string, emoji: string): Promise<void>;
getMessageReactions(chatId: string, messageId: string): Promise<MessageReaction[]>;
// Contacts
getContacts(): Promise<Contact[]>;
getContactById(contactId: string): Promise<Contact | null>;
checkNumberExists(number: string): Promise<boolean>;
// Groups - Basic
getGroups(): Promise<Group[]>;
// Groups - Extended (Phase 3)
getGroupInfo(groupId: string): Promise<GroupInfo | null>;
createGroup(name: string, participants: string[]): Promise<Group>;
addParticipants(groupId: string, participants: string[]): Promise<void>;
removeParticipants(groupId: string, participants: string[]): Promise<void>;
promoteParticipants(groupId: string, participants: string[]): Promise<void>;
demoteParticipants(groupId: string, participants: string[]): Promise<void>;
leaveGroup(groupId: string): Promise<void>;
setGroupSubject(groupId: string, subject: string): Promise<void>;
setGroupDescription(groupId: string, description: string): Promise<void>;
getGroupInviteCode(groupId: string): Promise<string>;
revokeGroupInviteCode(groupId: string): Promise<string>;
// Message Operations
deleteMessage(chatId: string, messageId: string, forEveryone?: boolean): Promise<void>;
getChatHistory(chatId: string, limit?: number, includeMedia?: boolean): Promise<IncomingMessage[]>;
// Contact Extended Operations
getProfilePicture(contactId: string): Promise<string | null>;
blockContact(contactId: string): Promise<void>;
unblockContact(contactId: string): Promise<void>;
// Labels (Phase 3) - WhatsApp Business only
getLabels(): Promise<Label[]>;
getLabelById(labelId: string): Promise<Label | null>;
getChatLabels(chatId: string): Promise<Label[]>;
addLabelToChat(chatId: string, labelId: string): Promise<void>;
removeLabelFromChat(chatId: string, labelId: string): Promise<void>;
// Channels/Newsletter (Phase 3)
getSubscribedChannels(): Promise<Channel[]>;
getChannelById(channelId: string): Promise<Channel | null>;
subscribeToChannel(inviteCode: string): Promise<Channel>;
unsubscribeFromChannel(channelId: string): Promise<void>;
getChannelMessages(channelId: string, limit?: number): Promise<ChannelMessage[]>;
// Status/Stories (Phase 3)
getContactStatuses(): Promise<Status[]>;
getContactStatus(contactId: string): Promise<Status[]>;
postTextStatus(text: string, options?: TextStatusOptions): Promise<StatusResult>;
postImageStatus(media: MediaInput, caption?: string): Promise<StatusResult>;
postVideoStatus(media: MediaInput, caption?: string): Promise<StatusResult>;
deleteStatus(statusId: string): Promise<void>;
// Catalog (Phase 3) - WhatsApp Business only
getCatalog(): Promise<Catalog | null>;
getProducts(options?: ProductQueryOptions): Promise<PaginatedProducts>;
getProduct(productId: string): Promise<Product | null>;
sendProduct(chatId: string, productId: string, body?: string): Promise<MessageResult>;
sendCatalog(chatId: string, body?: string): Promise<MessageResult>;
// Chats
getChats(): Promise<ChatSummary[]>;
sendSeen(chatId: string): Promise<boolean>;
}