zaileys 4.8.7 → 4.8.8

package/dist/builder/builder.d.ts

@@ -19,6 +19,8 @@ export interface BuilderSocketLike {
 export type TextOptions = {
     rich?: boolean;
 } & AIRichOptions;
+/** The pseudo-recipient WhatsApp uses for personal statuses (stories). */
+export declare const STATUS_BROADCAST_JID = "status@broadcast";
 export declare class MessageBuilder<State extends BuilderState> {
     protected readonly __state?: State;
     protected readonly socket: BuilderSocketLike;
@@ -55,6 +57,11 @@ export declare class MessageBuilder<State extends BuilderState> {
     reply(quoted: WAMessage | WAMessageKey): MessageBuilder<State>;
     mentions(jids: string[]): MessageBuilder<State>;
     mentionAll(): MessageBuilder<State>;
+    /**
+     * Sets who sees a status posted to `status@broadcast`. WhatsApp delivers a status only to the jids
+     * listed here — an empty list is accepted by the server but reaches nobody, so this is required.
+     */
+    audience(jids: string[]): MessageBuilder<State>;
     disappearing(seconds: number): MessageBuilder<State>;
     then<T = WAMessageKey>(this: MessageBuilder<'content-set'>, onResolved: (key: WAMessageKey) => T, onRejected?: (err: unknown) => T | PromiseLike<T>): Promise<T>;
     private uploadHeaderMedia;

package/dist/builder/state.d.ts

@@ -8,6 +8,7 @@ export type BuilderInternalState = {
     quoted?: WAMessage | WAMessageKey;
     mentions?: string[];
     mentionAll?: boolean;
+    statusJidList?: string[];
     disappearingSeconds?: number;
     resolveRecipient?: (raw: string) => Promise<string>;
     recordSent?: (message: WAMessage) => void;

package/dist/client/client.d.ts

@@ -10,6 +10,14 @@ import { TypedEventEmitter } from './event-emitter.js';
 import type { BaileysSocket, ClientEventMap, ClientOptions, ConnectionState, ProviderKind } from './types.js';
 import { CloudModule } from '../cloud/module.js';
 import { type WebhookHandler } from '../cloud/webhook.js';
+/**
+ * Reads the `<result>` payload of a `w:mex` reply. A jid with no username comes back as an
+ * `XWA2ResponseStatus` instead of an `XWA2Username`, so entries without one are skipped.
+ */
+export declare const parseMexUsers: (result: unknown) => Array<{
+    jid: string;
+    username: string;
+}>;
 export declare class Client extends TypedEventEmitter<ClientEventMap> {
     readonly sessionId: string;
     auth: AuthStoreBundle;
@@ -156,10 +164,23 @@ export declare class Client extends TypedEventEmitter<ClientEventMap> {
     private handleOpen;
     private resolveMessageForResend;
     private lidMapping;
+    /** One round trip for many jids, so resolving a whole participant list is not N lookups. */
+    private lidMapBulk;
     /** Resolve a `@lid` JID to its phone-number JID (uses WhatsApp's LID mapping; may hit the network). */
     lidToPn(lid: string): Promise<string | null>;
     /** Resolve a phone-number JID to its `@lid` JID (uses WhatsApp's LID mapping; may hit the network). */
     pnToLid(pn: string): Promise<string | null>;
+    /** Bulk {@link lidToPn}. Returns a `lid -> pn` map; jids WhatsApp could not resolve are simply absent. */
+    lidToPns(lids: string[]): Promise<Map<string, string>>;
+    /** Bulk {@link pnToLid}. Returns a `pn -> lid` map; jids WhatsApp could not resolve are simply absent. */
+    pnToLids(pns: string[]): Promise<Map<string, string>>;
+    /**
+     * Looks up WhatsApp usernames (`@handle`) for many jids in one round trip. Returns a `jid -> username`
+     * map; jids whose owner has not set a username are simply absent. Works best with `@lid` jids.
+     */
+    usernames(jids: string[]): Promise<Map<string, string>>;
+    /** Single-jid {@link usernames}. `null` when the account has no username or the lookup fails. */
+    getUsername(jid: string): Promise<string | null>;
     /**
      * Download media bytes for a message stored in the message store (by key).
      * Tries both `fromMe` variants. `null` when the message is unknown or carries no media.

package/dist/domain/chat.d.ts

@@ -22,6 +22,11 @@ export declare class ChatModule {
     markUnread(jid: string): Promise<void>;
     star(key: WAMessageKey, starred?: boolean): Promise<void>;
     unstar(key: WAMessageKey): Promise<void>;
+    /**
+     * Asks WhatsApp to resend older messages from before `oldest`. Returns the request id; the messages
+     * themselves arrive later on the `history-sync` event, not from this call.
+     */
+    fetchHistory(count: number, oldest: WAMessageKey, oldestTimestamp: number): Promise<string>;
     delete(jid: string): Promise<void>;
     clear(jid: string): Promise<void>;
 }

package/dist/domain/privacy.d.ts

@@ -1,5 +1,5 @@
 import type { DomainSocketLike } from './socket-like.js';
-import type { PrivacyConfig, PrivacySettings, WAReadReceiptsValue } from './types.js';
+import type { PrivacyConfig, PrivacySettings, WAPrivacyCallValue, WAReadReceiptsValue } from './types.js';
 export declare class PrivacyModule {
     private readonly getSocket;
     constructor(getSocket: () => DomainSocketLike | undefined);
@@ -12,4 +12,6 @@ export declare class PrivacyModule {
     unblock(jid: string): Promise<void>;
     blocklist(): Promise<string[]>;
     disappearingMode(seconds: number): Promise<void>;
+    /** Restricts who may call you. `known` blocks calls from anyone outside your contacts. */
+    call(value: WAPrivacyCallValue): Promise<void>;
 }

package/dist/domain/socket-like.d.ts

@@ -1,4 +1,4 @@
-import type { ChatModification, GroupMetadata, NewsletterMetadata, ParticipantAction, WAMediaUpload, WAPrivacyGroupAddValue, WAPrivacyOnlineValue, WAPrivacyValue, WAReadReceiptsValue } from 'baileys';
+import type { ChatModification, GroupMetadata, NewsletterMetadata, ParticipantAction, WAMediaUpload, WAMessageKey, WAPrivacyCallValue, WAPrivacyGroupAddValue, WAPrivacyOnlineValue, WAPrivacyValue, WAReadReceiptsValue } from 'baileys';
 import type { LinkedGroup } from './types.js';
 export interface DomainSocketLike {
     groupCreate(subject: string, participants: string[]): Promise<GroupMetadata>;
@@ -60,6 +60,7 @@ export interface DomainSocketLike {
     updateStatusPrivacy(value: WAPrivacyValue): Promise<void>;
     updateReadReceiptsPrivacy(value: WAReadReceiptsValue): Promise<void>;
     updateGroupsAddPrivacy(value: WAPrivacyGroupAddValue): Promise<void>;
+    updateCallPrivacy(value: WAPrivacyCallValue): Promise<void>;
     updateDefaultDisappearingMode(duration: number): Promise<void>;
     fetchPrivacySettings(force?: boolean): Promise<{
         [_: string]: string;
@@ -73,6 +74,7 @@ export interface DomainSocketLike {
     profilePictureUrl(jid: string, type?: 'image' | 'preview', timeoutMs?: number): Promise<string | undefined>;
     fetchStatus(jid: string): Promise<unknown>;
     chatModify(mod: ChatModification, jid: string): Promise<void>;
+    fetchMessageHistory(count: number, oldestMsgKey: WAMessageKey, oldestMsgTimestamp: number): Promise<string>;
     newsletterCreate(name: string, description?: string): Promise<NewsletterMetadata>;
     newsletterFollow(jid: string): Promise<unknown>;
     newsletterUnfollow(jid: string): Promise<unknown>;

package/dist/domain/types.d.ts

@@ -1,5 +1,5 @@
-export type { GroupMetadata, GroupParticipant, ParticipantAction, WAPrivacyValue, WAPrivacyOnlineValue, WAReadReceiptsValue, WAPrivacyGroupAddValue, NewsletterMetadata, WAMediaUpload, } from 'baileys';
-import type { WAPrivacyValue, WAPrivacyOnlineValue, WAReadReceiptsValue, WAPrivacyGroupAddValue } from 'baileys';
+export type { GroupMetadata, GroupParticipant, ParticipantAction, WAPrivacyValue, WAPrivacyOnlineValue, WAReadReceiptsValue, WAPrivacyGroupAddValue, WAPrivacyCallValue, NewsletterMetadata, WAMediaUpload, } from 'baileys';
+import type { WAPrivacyValue, WAPrivacyOnlineValue, WAReadReceiptsValue, WAPrivacyGroupAddValue, WAPrivacyCallValue } from 'baileys';
 export interface ParticipantUpdateResult {
     jid: string;
     status: string;
@@ -11,6 +11,8 @@ export interface PrivacyConfig {
     status?: WAPrivacyValue;
     readReceipts?: WAReadReceiptsValue;
     groupAdd?: WAPrivacyGroupAddValue;
+    /** Who may call you. `known` limits calls to your contacts. */
+    call?: WAPrivacyCallValue;
 }
 export type PrivacySettings = {
     [key: string]: string;

package/dist/events/call-metadata.d.ts

@@ -0,0 +1,7 @@
+import type { CallerInfo } from './types.js';
+/** Reads the caller details WhatsApp puts on a raw `<call>` stanza. Returns false when the node is not an offer. */
+export declare const rememberCallerInfo: (raw: unknown) => boolean;
+/** Pops the caller details captured for a call id, if the raw stanza carried any. */
+export declare const takeCallerInfo: (callId: string) => CallerInfo | undefined;
+/** Test seam: drops everything captured so far. */
+export declare const resetCallerInfo: () => void;

package/dist/events/context.d.ts

@@ -19,6 +19,16 @@ export interface MediaAttachment {
     fileName: string | null;
     fileSize: number | null;
     ptt: boolean;
+    /** Playback length in seconds, for audio and video. */
+    duration: number | null;
+    width: number | null;
+    height: number | null;
+    /** Page count, for documents. */
+    pages: number | null;
+    /** `true` for an animated sticker or a GIF-playback video. */
+    isAnimated: boolean;
+    /** Inline JPEG preview, when WhatsApp sent one. Lets you show a thumbnail without downloading. */
+    thumbnail: Buffer | null;
     buffer(): Promise<Buffer>;
     stream(): Promise<Readable>;
 }
@@ -147,6 +157,25 @@ export interface TemplateMedia {
     buttons: MessageButton[];
 }
 export type ContextMedia = MediaAttachment | PollMedia | ContactMedia | LocationMedia | EventMedia | AlbumMedia | GroupInviteMedia | ProductMedia | OrderMedia | PaymentMedia | LinkPreviewMedia | ButtonsMedia | ListMedia | InteractiveMedia | TemplateMedia;
+/** Attribution for a chat that started from a Meta ad (Click-to-WhatsApp). */
+export interface AdAttribution {
+    /** The click id to join against Meta Ads reporting. */
+    clickId?: string;
+    sourceId?: string;
+    sourceUrl?: string;
+    /** Which Meta surface the ad ran on, e.g. `facebook`, `instagram`. */
+    sourceApp?: string;
+    sourceType?: string;
+    title?: string;
+    body?: string;
+    thumbnailUrl?: string;
+    /** Campaign reference you set on the ad. */
+    ref?: string;
+}
+export interface BusinessInfo {
+    /** WhatsApp-verified business name. Unlike `senderName` this cannot be set by the sender. */
+    verifiedName: string;
+}
 export interface MessageContext {
     uniqueId: string;
     staticId: string;
@@ -158,6 +187,8 @@ export interface MessageContext {
     senderId: string;
     senderLid: string | null;
     senderName: string | null;
+    /** WhatsApp username (the `@handle`), without the `@`. Only sent for accounts that set one. */
+    senderUsername: string | null;
     senderDevice: SenderDevice;
     timestamp: number;
     text: string;
@@ -170,6 +201,20 @@ export interface MessageContext {
     isViewOnce: boolean;
     isEphemeral: boolean;
     isForwarded: boolean;
+    /** `true` for a backlog message replayed after a reconnect. Skip these to avoid answering twice. */
+    isOffline: boolean;
+    /** How many hops this message has been forwarded. `>= 5` is WhatsApp's "forwarded many times". */
+    forwardCount: number;
+    /** The chat's disappearing timer in seconds, or `null` when messages are kept. */
+    ephemeralDuration: number | null;
+    /** Whether WhatsApp addressed this message by phone number or by LID. */
+    addressingMode: 'pn' | 'lid';
+    /** JIDs of groups tagged in the message (community `@group` mentions). */
+    mentionedGroups: string[];
+    /** Present only on the first message of a chat opened from a Meta ad. */
+    ad?: AdAttribution;
+    /** Present only when the sender is a verified WhatsApp Business account. */
+    business?: BusinessInfo;
     isQuestion: boolean;
     isPrefix: boolean;
     isTagMe: boolean;
@@ -217,6 +262,13 @@ export interface BuildContextInput {
     isForwarded: boolean;
     isBroadcast: boolean;
     isNewsletter: boolean;
+    isOffline?: boolean;
+    forwardCount?: number;
+    ephemeralDuration?: number | null;
+    addressingMode?: 'pn' | 'lid';
+    mentionedGroups?: string[];
+    ad?: AdAttribution;
+    business?: BusinessInfo;
     prefixes: string[];
     citationConfig?: CitationConfig;
     lidMap?: Map<string, string>;

package/dist/events/decoders/messages.d.ts

@@ -7,6 +7,8 @@ export interface DecodeContext {
     selfLid?: string;
     selfName?: string;
     lidMap?: Map<string, string>;
+    /** WhatsApp replays a reconnect's backlog as `append`; live traffic arrives as `notify`. */
+    isOffline?: boolean;
     logger?: DownloadLogger;
     channelId?: string;
     receiverId?: string;

package/dist/events/decoders/mutations.d.ts

@@ -4,6 +4,8 @@ import { type LongLike } from './_shared.js';
 export interface MutationContext {
     selfJid: string;
     pushName?: string;
+    /** Looks up the original poll so a vote's option hashes can be turned back into their text. */
+    resolvePoll?: (id: string, remoteJid: string) => Promise<proto.IWebMessageInfo | null>;
 }
 export interface ReactionItem {
     key: WAMessageKey;

package/dist/events/index.d.ts

@@ -1,4 +1,4 @@
 export * from './guards.js';
-export type { ButtonClickPayload, CallBase, CallPayload, DeletePayload, EditPayload, GroupJoinPayload, GroupLeavePayload, GroupParticipantInfo, GroupUpdatePayload, HistorySyncPayload, InboundEventMap, InboundEventName, LimitedPayload, ListSelectPayload, MediaDescriptor, MediaDownloadResult, MediaKind, MemberTagPayload, NewsletterPayload, PollVotePayload, PresencePayload, QuotedRef, ReactionPayload, SenderInfo, } from './types.js';
+export type { ButtonClickPayload, CallBase, CallerInfo, CallPayload, DeletePayload, EditPayload, GroupJoinPayload, GroupLeavePayload, GroupParticipantInfo, GroupUpdatePayload, HistorySyncPayload, InboundEventMap, InboundEventName, LimitedPayload, ListSelectPayload, MediaDescriptor, MediaDownloadResult, MediaKind, MemberTagPayload, NewsletterPayload, PollVotePayload, PresencePayload, QuotedRef, ReactionPayload, SenderInfo, } from './types.js';
 export type { BuildContextInput, ChatType, CitationConfig, CitationPredicates, ContextMedia, MentionAllContext, MentionContext, MessageContext, SenderDevice, } from './context.js';
 export { buildMessageContext } from './context.js';

package/dist/events/types.d.ts

@@ -54,7 +54,10 @@ export interface DeletePayload {
 }
 export interface PollVotePayload {
     pollKey: WAMessageKey;
+    /** Raw SHA-256 hashes WhatsApp sends. Use {@link PollVotePayload.options} for readable text. */
     selectedOptions: string[];
+    /** The option text the voter picked. Needs the original poll in the store; empty when unavailable. */
+    options(): Promise<string[]>;
     voter: SenderInfo;
     timestamp: number;
 }
@@ -109,6 +112,25 @@ export type CallPayload = (CallBase & {
 }) | (CallBase & {
     kind: 'ended';
 });
+export interface CallerInfo {
+    /** Caller platform as WhatsApp reports it, e.g. `iphone`, `android`, `smba`. More reliable than a jid device index. */
+    platform?: string;
+    /** Caller's WhatsApp app version, e.g. `2.26.30.78`. */
+    appVersion?: string;
+    /** Caller's pushname carried on the call stanza. */
+    name?: string;
+    /** ISO 3166 country the caller is dialling from, e.g. `ID`. */
+    countryCode?: string;
+    /** Caller's phone-number jid — present even when the call itself is addressed by LID. */
+    phoneJid?: string;
+    /** Raw network medium code the caller's device reported. */
+    networkMedium?: number;
+    /** Screen size the caller's device advertised. Video calls only. */
+    screen?: {
+        width: number;
+        height: number;
+    };
+}
 export interface CallBase {
     callId: string;
     from: string;
@@ -116,6 +138,8 @@ export interface CallBase {
     isVideo: boolean;
     timestamp: number;
     status?: string;
+    /** Extra caller details from the raw call stanza. Absent when WhatsApp did not send them. */
+    caller?: CallerInfo;
 }
 export interface HistorySyncPayload {
     syncType: string;