zaileys 4.0.5 → 4.1.1

package/dist/index.d.cts

@@ -180,6 +180,7 @@ interface BuilderSocketLike {
         messageId: string;
         additionalNodes?: unknown[];
     }): Promise<string>;
+    chatModify?(mod: unknown, jid: string): Promise<void>;
     user?: {
         id?: string | null;
     } | null;
@@ -319,6 +320,27 @@ declare class ZaileysDomainError extends Error {
     });
 }
 
+type OperationGuardClock = {
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+};
+/**
+ * Per-category minimum-interval throttle for sensitive account operations
+ * (group/community/newsletter create, join, member changes). Spacing these out
+ * avoids the rapid-fire pattern WhatsApp flags as automated/bulk abuse.
+ */
+type OperationCategory = 'group.create' | 'group.join' | 'group.participants' | 'group.update' | 'community.create' | 'community.join' | 'community.update' | 'newsletter.create' | 'newsletter.follow' | 'newsletter.update';
+interface OperationGuardOptions {
+    /** Master switch. When `false` operations run with no spacing. Default `true`. */
+    enabled?: boolean;
+    /** Per-category minimum interval in ms, overriding the built-in defaults. */
+    intervalsMs?: Partial<Record<OperationCategory, number>>;
+}
+interface OperationGuard {
+    run<T>(category: OperationCategory, op: () => Promise<T>): Promise<T>;
+}
+declare function createOperationGuard(options?: OperationGuardOptions, clock?: OperationGuardClock): OperationGuard;
+
 interface DomainSocketLike {
     groupCreate(subject: string, participants: string[]): Promise<GroupMetadata>;
     groupParticipantsUpdate(jid: string, participants: string[], action: ParticipantAction): Promise<{
@@ -377,9 +399,11 @@ interface DomainSocketLike {
 
 declare class GroupModule {
     private readonly getSocket;
-    constructor(getSocket: () => DomainSocketLike | undefined);
+    private readonly guard?;
+    constructor(getSocket: () => DomainSocketLike | undefined, guard?: OperationGuard | undefined);
     protected requireSocket(): DomainSocketLike;
     private mapParticipants;
+    private run;
     create(subject: string, participants: string[]): Promise<GroupMetadata>;
     addMember(groupId: string, jids: string[]): Promise<ParticipantUpdateResult[]>;
     removeMember(groupId: string, jids: string[]): Promise<ParticipantUpdateResult[]>;
@@ -413,8 +437,10 @@ declare class PrivacyModule {
 
 declare class NewsletterModule {
     private readonly getSocket;
-    constructor(getSocket: () => DomainSocketLike | undefined);
+    private readonly guard?;
+    constructor(getSocket: () => DomainSocketLike | undefined, guard?: OperationGuard | undefined);
     protected requireSocket(): DomainSocketLike;
+    private run;
     create(name: string, opts?: {
         description?: string;
         picture?: Buffer;
@@ -432,8 +458,10 @@ declare class NewsletterModule {
 
 declare class CommunityModule {
     private readonly getSocket;
-    constructor(getSocket: () => DomainSocketLike | undefined);
+    private readonly guard?;
+    constructor(getSocket: () => DomainSocketLike | undefined, guard?: OperationGuard | undefined);
     protected requireSocket(): DomainSocketLike;
+    private run;
     create(subject: string, body: string): Promise<GroupMetadata>;
     createGroup(subject: string, participants: string[], communityId: string): Promise<GroupMetadata>;
     linkGroup(communityId: string, groupId: string): Promise<void>;
@@ -798,9 +826,76 @@ interface AuthStoreBundle {
     readonly signal: AuthStore;
 }
 
-type DisconnectReasonDomain = 'logged-out' | 'connection-replaced' | 'forbidden' | 'restart-required' | 'bad-session' | 'connection-closed' | 'connection-lost' | 'multi-device-mismatch' | 'unavailable-service' | 'unknown';
+type WAPresence = 'unavailable' | 'available' | 'composing' | 'recording' | 'paused';
+interface AutomationSocketLike {
+    sendPresenceUpdate(type: WAPresence, toJid?: string): Promise<void>;
+}
+/** Drops presence updates that repeat the same (type, chat) inside `minIntervalMs`. */
+interface PresenceThrottleOptions {
+    enabled?: boolean;
+    minIntervalMs?: number;
+}
+type PresenceClock = {
+    now?: () => number;
+};
+declare class PresenceModule {
+    private readonly getSocket;
+    private readonly throttleEnabled;
+    private readonly minIntervalMs;
+    private readonly now;
+    private readonly lastSent;
+    constructor(getSocket: () => AutomationSocketLike | undefined, throttle?: PresenceThrottleOptions, clock?: PresenceClock);
+    protected requireSocket(): AutomationSocketLike;
+    private throttled;
+    private update;
+    private scheduleClear;
+    online(): Promise<void>;
+    offline(): Promise<void>;
+    typing(jid: string, ms?: number): Promise<void>;
+    recording(jid: string, ms?: number): Promise<void>;
+}
+
+/**
+ * Bounds QR and pairing-code regeneration across a client's lifetime to avoid
+ * tripping WhatsApp's spam/automation restriction. Each reconnect creates a fresh
+ * socket which re-emits a QR or requests a new pairing code; without a budget and
+ * cooldown this loops unbounded and gets the account restricted.
+ */
+interface AuthGuardOptions {
+    /** Master switch. When `false` the guard never blocks (legacy behaviour). Default `true`. */
+    enabled?: boolean;
+    /** Total QR codes emitted before the guard stops and signals exhaustion. Default `5`. */
+    maxQrAttempts?: number;
+    /** Total pairing-code requests before the guard stops and signals exhaustion. Default `3`. */
+    maxPairingAttempts?: number;
+    /** Base cooldown between pairing-code requests; escalates per attempt. Default `60000`. */
+    pairingCooldownMs?: number;
+}
+type AuthAttemptBlockReason = 'budget-exhausted' | 'cooldown';
+interface AuthAttemptDecision {
+    allowed: boolean;
+    reason?: AuthAttemptBlockReason;
+    waitMs: number;
+    attempts: number;
+    max: number;
+}
+interface AuthGuard {
+    /** Decide whether a new auth attempt of `kind` is permitted at time `now` (does not mutate). */
+    evaluate(kind: ConnectionAuthType, now: number): AuthAttemptDecision;
+    /** Record that an attempt of `kind` was actually issued at time `now`. */
+    record(kind: ConnectionAuthType, now: number): void;
+    /** Clear all counters and cooldowns (call on a successful connection or manual restart). */
+    reset(): void;
+    readonly enabled: boolean;
+    readonly qrAttempts: number;
+    readonly pairingAttempts: number;
+}
+declare function createAuthGuard(options?: AuthGuardOptions): AuthGuard;
+
+type DisconnectReasonDomain = 'logged-out' | 'connection-replaced' | 'forbidden' | 'restart-required' | 'bad-session' | 'connection-closed' | 'connection-lost' | 'multi-device-mismatch' | 'unavailable-service' | 'rate-limited' | 'unknown';
 declare function mapDisconnectReason(code: number | undefined): DisconnectReasonDomain;
 declare function isFatalDisconnect(reason: DisconnectReasonDomain): boolean;
+declare function isRateLimited(reason: DisconnectReasonDomain): boolean;
 declare function shouldClearAuth(reason: DisconnectReasonDomain): boolean;
 declare function shouldReconnect(reason: DisconnectReasonDomain): boolean;
 
@@ -819,6 +914,8 @@ interface ReconnectOptions {
     initialDelayMs?: number;
     maxDelayMs?: number;
     jitterFactor?: number;
+    /** Fixed backoff applied when the disconnect reason is `rate-limited` (429). Default `300000`. */
+    rateLimitedDelayMs?: number;
 }
 interface ClientOptions {
     sessionId?: string;
@@ -836,6 +933,14 @@ interface ClientOptions {
     commandPrefix?: string | string[];
     citation?: CitationConfig;
     ignoreMe?: boolean;
+    /** Bounds QR/pairing regeneration to avoid spam restriction. ON by default; `{ enabled: false }` to opt out. */
+    authGuard?: AuthGuardOptions;
+    /** Spaces out sensitive group/community/newsletter operations. ON by default; `{ enabled: false }` to opt out. */
+    operationGuard?: OperationGuardOptions;
+    /** Drops duplicate presence (typing/recording/online) updates within a window. ON by default. */
+    presence?: PresenceThrottleOptions;
+    /** Max scheduled messages dispatched per second, smoothing backlog bursts. Default `1`; `0` disables. */
+    scheduleRateLimitPerSec?: number;
 }
 type ConnectionEventMap = {
     connect: {
@@ -867,6 +972,12 @@ type ConnectionEventMap = {
         delayMs: number;
         reason: DisconnectReasonDomain;
     };
+    'auth-exhausted': {
+        sessionId: string;
+        kind: ConnectionAuthType;
+        attempts: number;
+        max: number;
+    };
     error: {
         sessionId: string;
         error: Error;
@@ -983,22 +1094,6 @@ type BroadcastDeps = {
 };
 declare function runBroadcast(jids: string[], build: (b: MessageBuilder<'init'>) => MessageBuilder<'content-set'>, deps: BroadcastDeps, options?: BroadcastOptions): Promise<BroadcastResult>;
 
-type WAPresence = 'unavailable' | 'available' | 'composing' | 'recording' | 'paused';
-interface AutomationSocketLike {
-    sendPresenceUpdate(type: WAPresence, toJid?: string): Promise<void>;
-}
-declare class PresenceModule {
-    private readonly getSocket;
-    constructor(getSocket: () => AutomationSocketLike | undefined);
-    protected requireSocket(): AutomationSocketLike;
-    private update;
-    private scheduleClear;
-    online(): Promise<void>;
-    offline(): Promise<void>;
-    typing(jid: string, ms?: number): Promise<void>;
-    recording(jid: string, ms?: number): Promise<void>;
-}
-
 type ScheduledContentSnapshot = {
     recipient: string;
     content: AnyMessageContent;
@@ -1014,6 +1109,7 @@ type SchedulerDeps = {
     now?: () => number;
     timer?: SchedulerTimer;
     logger?: Logger;
+    acquire?: () => Promise<void>;
 };
 type ScheduleHandle = {
     id: string;
@@ -1025,6 +1121,7 @@ declare class Scheduler {
     private readonly now;
     private readonly timer;
     private readonly logger;
+    private readonly acquire;
     private readonly memory;
     private readonly timers;
     constructor(deps: SchedulerDeps);
@@ -1072,6 +1169,11 @@ declare class Client extends TypedEventEmitter<ClientEventMap> {
     private readonly baileysExtra;
     private readonly machine;
     private reconnectStrategy;
+    private readonly authGuard;
+    private readonly operationGuard;
+    private readonly presenceThrottle;
+    private readonly scheduleLimiter;
+    private authExhausted;
     private _socket;
     private reconnectTimer;
     private listenerCleanup;
@@ -1137,7 +1239,9 @@ declare class Client extends TypedEventEmitter<ClientEventMap> {
     private wireSocket;
     private handleConnectionUpdate;
     private handleQrUpdate;
+    private handleAuthExhausted;
     private handleOpen;
+    private resolveMessageForResend;
     private lookupQuoted;
     private handleClose;
     private rejectPendingConnect;
@@ -1258,8 +1362,6 @@ interface CacheableAuthStoreOptions {
         warn?: (msg: unknown) => void;
         error?: (msg: unknown) => void;
     };
-    cacheSize?: number;
-    cacheTtlSeconds?: number;
 }
 declare function makeCacheableAuthStore(bundle: AuthStoreBundle, options?: CacheableAuthStoreOptions): AuthStoreBundle;
 
@@ -1670,4 +1772,4 @@ declare class Media {
     toBuffer(): Promise<Buffer>;
 }
 
-export { type AddressButton, type AlbumItem, type AudioOptions, AudioProcessor, type AudioType, type AuthCredsStore, type AuthStore, type AuthStoreBundle, type AuthStoreKey, type AuthStoreValue, type AutomationErrorCode, type AutomationSocketLike, type BaileysSocket, type BaileysSocketLike, type BottomSheetOptions, type BroadcastDeps, type BroadcastOptions, type BroadcastResult, BufferConverter, type BuildContextInput, type BuilderContext, type BuilderErrorCode, type BuilderSocketLike, type BuilderState, type ButtonClickPayload, type ButtonDef, type CacheableAuthStoreOptions, type CallBase, type CallButton, type CallPayload, type CancelReminderButton, type ChatType, type CitationConfig, type CitationPredicates, Client, type ClientEventMap, type ClientEventName, type ClientOptions, type CommandContext, type CommandDefinition, type CommandErrorCode, type CommandHandler, type CommandPrefix, CommandRegistry, CommunityModule, type ConnectionAuthType, type ConnectionEventHandler, type ConnectionEventMap, type ConnectionEventName, type ConnectionState, type ConnectionStateMachine, type ContextMedia, ConvexAuthStore, type ConvexAuthStoreOptions, ConvexMessageStore, type ConvexMessageStoreOptions, type CopyButton, type CreateLoggerOptions, type DeleteOptions, type DeletePayload, type DisconnectReasonDomain, type DispatcherDeps, type DispatcherHandle, type DocumentOptions, DocumentProcessor, type DomainErrorCode, type DomainSocketLike, EditBuilder, type EditPayload, FFMPEG_CONSTANTS, type FFmpegConfig, FFmpegProcessor, FileAuthStore, type FileAuthStoreOptions, type FileExtension, FileManager, type GroupJoinPayload, type GroupLeavePayload, GroupModule, type GroupParticipantInfo, type GroupUpdatePayload, type HistorySyncPayload, type ImageOptions, ImageProcessor, type InboundEventMap, type InboundEventName, type InteractiveButton, type LIDMapping, type LIDMappingUpdatePayload, type LimitedPayload, type LimitedTimeOfferOptions, type LinkedGroup, type ListOptions, type ListSection, type ListSelectPayload, type LocationOptions, type LocationRequestButton, type Logger, type LoggerLevel, Media, type MediaDescriptor, type MediaDownloadResult, type MediaInput, type MediaKind, type MediaSource, type MemberTagPayload, MemoryAuthStore, MemoryMessageStore, type MentionAllContext, type MentionContext, MessageBuilder, type MessageContext, type MessageStore, type MessageStoreListOptions, type Middleware, MimeValidator, NewsletterModule, type NewsletterPayload, type PairingFlow, type PairingFlowOptions, type PairingFlowResult, type ParsedArgs, type ParticipantUpdateResult, type PollOptions, type PollVotePayload, PostgresAuthStore, type PostgresAuthStoreOptions, PostgresMessageStore, type PostgresMessageStoreOptions, PresenceModule, type PresencePayload, type PrivacyConfig, PrivacyModule, type PrivacySettings, type QuotedRef, RateLimiter, type RateLimiterClock, type RateLimiterOptions, type ReactionPayload, type ReconnectDecision, type ReconnectOptions, type ReconnectStrategy, type ReconnectStrategyDeps, RedisAuthStore, type RedisAuthStoreOptions, RedisMessageStore, type RedisMessageStoreOptions, type ReminderButton, type ReplyButton, type ResolvedCommand, type RetryPolicy, SELF_ONLY_PROTOCOL_TYPES, type ScheduleHandle, type ScheduledContentSnapshot, type ScheduledJob, type ScheduledJobRecord, Scheduler, type SchedulerDeps, type SchedulerTimer, type SelfOnlyProtocolType, type SenderDevice, type SenderInfo, SqliteAuthStore, type SqliteAuthStoreOptions, SqliteMessageStore, type SqliteMessageStoreOptions, type StateTransitionListener, type StickerMetadataType, type StickerOptions, StickerProcessor, type StickerShapeType, type StoreErrorCode, TaskQueue, type TaskQueueClock, type TaskQueueOptions, type TemplateOptions, type TextOptions, TypedEventEmitter, type TypedEventEmitterOptions, type UpsertPayload, type UrlButton, type UsernameResolveSocketLike, type VideoOptions, VideoProcessor, type WAPresence, ZaileysAutomationError, ZaileysBuilderError, ZaileysCommandError, ZaileysDomainError, type ZaileysLogger, ZaileysStoreError, adoptLogger, attachCommandDispatcher, buildMessageContext, chunk, createConnectionStateMachine, createLogger, createPairingFlow, createReconnectStrategy, deleteMessage, detectFileType, dropSpoofedSelfOnly, ffmpegTransform, forwardMessage, generateId, initializeFFmpeg, isFatalDisconnect, isJid, makeCacheableAuthStore, mapDisconnectReason, normalizePhoneNumber, parseCommand, printQrToTerminal, reactToMessage, renderQrInTerminal, resolveUsername, runBroadcast, runMiddleware, shouldClearAuth, shouldReconnect, signalKeyStoreFromAuthStore, validateE164 };
+export { type AddressButton, type AlbumItem, type AudioOptions, AudioProcessor, type AudioType, type AuthAttemptBlockReason, type AuthAttemptDecision, type AuthCredsStore, type AuthGuard, type AuthGuardOptions, type AuthStore, type AuthStoreBundle, type AuthStoreKey, type AuthStoreValue, type AutomationErrorCode, type AutomationSocketLike, type BaileysSocket, type BaileysSocketLike, type BottomSheetOptions, type BroadcastDeps, type BroadcastOptions, type BroadcastResult, BufferConverter, type BuildContextInput, type BuilderContext, type BuilderErrorCode, type BuilderSocketLike, type BuilderState, type ButtonClickPayload, type ButtonDef, type CacheableAuthStoreOptions, type CallBase, type CallButton, type CallPayload, type CancelReminderButton, type ChatType, type CitationConfig, type CitationPredicates, Client, type ClientEventMap, type ClientEventName, type ClientOptions, type CommandContext, type CommandDefinition, type CommandErrorCode, type CommandHandler, type CommandPrefix, CommandRegistry, CommunityModule, type ConnectionAuthType, type ConnectionEventHandler, type ConnectionEventMap, type ConnectionEventName, type ConnectionState, type ConnectionStateMachine, type ContextMedia, ConvexAuthStore, type ConvexAuthStoreOptions, ConvexMessageStore, type ConvexMessageStoreOptions, type CopyButton, type CreateLoggerOptions, type DeleteOptions, type DeletePayload, type DisconnectReasonDomain, type DispatcherDeps, type DispatcherHandle, type DocumentOptions, DocumentProcessor, type DomainErrorCode, type DomainSocketLike, EditBuilder, type EditPayload, FFMPEG_CONSTANTS, type FFmpegConfig, FFmpegProcessor, FileAuthStore, type FileAuthStoreOptions, type FileExtension, FileManager, type GroupJoinPayload, type GroupLeavePayload, GroupModule, type GroupParticipantInfo, type GroupUpdatePayload, type HistorySyncPayload, type ImageOptions, ImageProcessor, type InboundEventMap, type InboundEventName, type InteractiveButton, type LIDMapping, type LIDMappingUpdatePayload, type LimitedPayload, type LimitedTimeOfferOptions, type LinkedGroup, type ListOptions, type ListSection, type ListSelectPayload, type LocationOptions, type LocationRequestButton, type Logger, type LoggerLevel, Media, type MediaDescriptor, type MediaDownloadResult, type MediaInput, type MediaKind, type MediaSource, type MemberTagPayload, MemoryAuthStore, MemoryMessageStore, type MentionAllContext, type MentionContext, MessageBuilder, type MessageContext, type MessageStore, type MessageStoreListOptions, type Middleware, MimeValidator, NewsletterModule, type NewsletterPayload, type OperationCategory, type OperationGuard, type OperationGuardClock, type OperationGuardOptions, type PairingFlow, type PairingFlowOptions, type PairingFlowResult, type ParsedArgs, type ParticipantUpdateResult, type PollOptions, type PollVotePayload, PostgresAuthStore, type PostgresAuthStoreOptions, PostgresMessageStore, type PostgresMessageStoreOptions, type PresenceClock, PresenceModule, type PresencePayload, type PresenceThrottleOptions, type PrivacyConfig, PrivacyModule, type PrivacySettings, type QuotedRef, RateLimiter, type RateLimiterClock, type RateLimiterOptions, type ReactionPayload, type ReconnectDecision, type ReconnectOptions, type ReconnectStrategy, type ReconnectStrategyDeps, RedisAuthStore, type RedisAuthStoreOptions, RedisMessageStore, type RedisMessageStoreOptions, type ReminderButton, type ReplyButton, type ResolvedCommand, type RetryPolicy, SELF_ONLY_PROTOCOL_TYPES, type ScheduleHandle, type ScheduledContentSnapshot, type ScheduledJob, type ScheduledJobRecord, Scheduler, type SchedulerDeps, type SchedulerTimer, type SelfOnlyProtocolType, type SenderDevice, type SenderInfo, SqliteAuthStore, type SqliteAuthStoreOptions, SqliteMessageStore, type SqliteMessageStoreOptions, type StateTransitionListener, type StickerMetadataType, type StickerOptions, StickerProcessor, type StickerShapeType, type StoreErrorCode, TaskQueue, type TaskQueueClock, type TaskQueueOptions, type TemplateOptions, type TextOptions, TypedEventEmitter, type TypedEventEmitterOptions, type UpsertPayload, type UrlButton, type UsernameResolveSocketLike, type VideoOptions, VideoProcessor, type WAPresence, ZaileysAutomationError, ZaileysBuilderError, ZaileysCommandError, ZaileysDomainError, type ZaileysLogger, ZaileysStoreError, adoptLogger, attachCommandDispatcher, buildMessageContext, chunk, createAuthGuard, createConnectionStateMachine, createLogger, createOperationGuard, createPairingFlow, createReconnectStrategy, deleteMessage, detectFileType, dropSpoofedSelfOnly, ffmpegTransform, forwardMessage, generateId, initializeFFmpeg, isFatalDisconnect, isJid, isRateLimited, makeCacheableAuthStore, mapDisconnectReason, normalizePhoneNumber, parseCommand, printQrToTerminal, reactToMessage, renderQrInTerminal, resolveUsername, runBroadcast, runMiddleware, shouldClearAuth, shouldReconnect, signalKeyStoreFromAuthStore, validateE164 };

package/dist/index.d.ts

@@ -180,6 +180,7 @@ interface BuilderSocketLike {
         messageId: string;
         additionalNodes?: unknown[];
     }): Promise<string>;
+    chatModify?(mod: unknown, jid: string): Promise<void>;
     user?: {
         id?: string | null;
     } | null;
@@ -319,6 +320,27 @@ declare class ZaileysDomainError extends Error {
     });
 }
 
+type OperationGuardClock = {
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+};
+/**
+ * Per-category minimum-interval throttle for sensitive account operations
+ * (group/community/newsletter create, join, member changes). Spacing these out
+ * avoids the rapid-fire pattern WhatsApp flags as automated/bulk abuse.
+ */
+type OperationCategory = 'group.create' | 'group.join' | 'group.participants' | 'group.update' | 'community.create' | 'community.join' | 'community.update' | 'newsletter.create' | 'newsletter.follow' | 'newsletter.update';
+interface OperationGuardOptions {
+    /** Master switch. When `false` operations run with no spacing. Default `true`. */
+    enabled?: boolean;
+    /** Per-category minimum interval in ms, overriding the built-in defaults. */
+    intervalsMs?: Partial<Record<OperationCategory, number>>;
+}
+interface OperationGuard {
+    run<T>(category: OperationCategory, op: () => Promise<T>): Promise<T>;
+}
+declare function createOperationGuard(options?: OperationGuardOptions, clock?: OperationGuardClock): OperationGuard;
+
 interface DomainSocketLike {
     groupCreate(subject: string, participants: string[]): Promise<GroupMetadata>;
     groupParticipantsUpdate(jid: string, participants: string[], action: ParticipantAction): Promise<{
@@ -377,9 +399,11 @@ interface DomainSocketLike {
 
 declare class GroupModule {
     private readonly getSocket;
-    constructor(getSocket: () => DomainSocketLike | undefined);
+    private readonly guard?;
+    constructor(getSocket: () => DomainSocketLike | undefined, guard?: OperationGuard | undefined);
     protected requireSocket(): DomainSocketLike;
     private mapParticipants;
+    private run;
     create(subject: string, participants: string[]): Promise<GroupMetadata>;
     addMember(groupId: string, jids: string[]): Promise<ParticipantUpdateResult[]>;
     removeMember(groupId: string, jids: string[]): Promise<ParticipantUpdateResult[]>;
@@ -413,8 +437,10 @@ declare class PrivacyModule {
 
 declare class NewsletterModule {
     private readonly getSocket;
-    constructor(getSocket: () => DomainSocketLike | undefined);
+    private readonly guard?;
+    constructor(getSocket: () => DomainSocketLike | undefined, guard?: OperationGuard | undefined);
     protected requireSocket(): DomainSocketLike;
+    private run;
     create(name: string, opts?: {
         description?: string;
         picture?: Buffer;
@@ -432,8 +458,10 @@ declare class NewsletterModule {
 
 declare class CommunityModule {
     private readonly getSocket;
-    constructor(getSocket: () => DomainSocketLike | undefined);
+    private readonly guard?;
+    constructor(getSocket: () => DomainSocketLike | undefined, guard?: OperationGuard | undefined);
     protected requireSocket(): DomainSocketLike;
+    private run;
     create(subject: string, body: string): Promise<GroupMetadata>;
     createGroup(subject: string, participants: string[], communityId: string): Promise<GroupMetadata>;
     linkGroup(communityId: string, groupId: string): Promise<void>;
@@ -798,9 +826,76 @@ interface AuthStoreBundle {
     readonly signal: AuthStore;
 }
 
-type DisconnectReasonDomain = 'logged-out' | 'connection-replaced' | 'forbidden' | 'restart-required' | 'bad-session' | 'connection-closed' | 'connection-lost' | 'multi-device-mismatch' | 'unavailable-service' | 'unknown';
+type WAPresence = 'unavailable' | 'available' | 'composing' | 'recording' | 'paused';
+interface AutomationSocketLike {
+    sendPresenceUpdate(type: WAPresence, toJid?: string): Promise<void>;
+}
+/** Drops presence updates that repeat the same (type, chat) inside `minIntervalMs`. */
+interface PresenceThrottleOptions {
+    enabled?: boolean;
+    minIntervalMs?: number;
+}
+type PresenceClock = {
+    now?: () => number;
+};
+declare class PresenceModule {
+    private readonly getSocket;
+    private readonly throttleEnabled;
+    private readonly minIntervalMs;
+    private readonly now;
+    private readonly lastSent;
+    constructor(getSocket: () => AutomationSocketLike | undefined, throttle?: PresenceThrottleOptions, clock?: PresenceClock);
+    protected requireSocket(): AutomationSocketLike;
+    private throttled;
+    private update;
+    private scheduleClear;
+    online(): Promise<void>;
+    offline(): Promise<void>;
+    typing(jid: string, ms?: number): Promise<void>;
+    recording(jid: string, ms?: number): Promise<void>;
+}
+
+/**
+ * Bounds QR and pairing-code regeneration across a client's lifetime to avoid
+ * tripping WhatsApp's spam/automation restriction. Each reconnect creates a fresh
+ * socket which re-emits a QR or requests a new pairing code; without a budget and
+ * cooldown this loops unbounded and gets the account restricted.
+ */
+interface AuthGuardOptions {
+    /** Master switch. When `false` the guard never blocks (legacy behaviour). Default `true`. */
+    enabled?: boolean;
+    /** Total QR codes emitted before the guard stops and signals exhaustion. Default `5`. */
+    maxQrAttempts?: number;
+    /** Total pairing-code requests before the guard stops and signals exhaustion. Default `3`. */
+    maxPairingAttempts?: number;
+    /** Base cooldown between pairing-code requests; escalates per attempt. Default `60000`. */
+    pairingCooldownMs?: number;
+}
+type AuthAttemptBlockReason = 'budget-exhausted' | 'cooldown';
+interface AuthAttemptDecision {
+    allowed: boolean;
+    reason?: AuthAttemptBlockReason;
+    waitMs: number;
+    attempts: number;
+    max: number;
+}
+interface AuthGuard {
+    /** Decide whether a new auth attempt of `kind` is permitted at time `now` (does not mutate). */
+    evaluate(kind: ConnectionAuthType, now: number): AuthAttemptDecision;
+    /** Record that an attempt of `kind` was actually issued at time `now`. */
+    record(kind: ConnectionAuthType, now: number): void;
+    /** Clear all counters and cooldowns (call on a successful connection or manual restart). */
+    reset(): void;
+    readonly enabled: boolean;
+    readonly qrAttempts: number;
+    readonly pairingAttempts: number;
+}
+declare function createAuthGuard(options?: AuthGuardOptions): AuthGuard;
+
+type DisconnectReasonDomain = 'logged-out' | 'connection-replaced' | 'forbidden' | 'restart-required' | 'bad-session' | 'connection-closed' | 'connection-lost' | 'multi-device-mismatch' | 'unavailable-service' | 'rate-limited' | 'unknown';
 declare function mapDisconnectReason(code: number | undefined): DisconnectReasonDomain;
 declare function isFatalDisconnect(reason: DisconnectReasonDomain): boolean;
+declare function isRateLimited(reason: DisconnectReasonDomain): boolean;
 declare function shouldClearAuth(reason: DisconnectReasonDomain): boolean;
 declare function shouldReconnect(reason: DisconnectReasonDomain): boolean;
 
@@ -819,6 +914,8 @@ interface ReconnectOptions {
     initialDelayMs?: number;
     maxDelayMs?: number;
     jitterFactor?: number;
+    /** Fixed backoff applied when the disconnect reason is `rate-limited` (429). Default `300000`. */
+    rateLimitedDelayMs?: number;
 }
 interface ClientOptions {
     sessionId?: string;
@@ -836,6 +933,14 @@ interface ClientOptions {
     commandPrefix?: string | string[];
     citation?: CitationConfig;
     ignoreMe?: boolean;
+    /** Bounds QR/pairing regeneration to avoid spam restriction. ON by default; `{ enabled: false }` to opt out. */
+    authGuard?: AuthGuardOptions;
+    /** Spaces out sensitive group/community/newsletter operations. ON by default; `{ enabled: false }` to opt out. */
+    operationGuard?: OperationGuardOptions;
+    /** Drops duplicate presence (typing/recording/online) updates within a window. ON by default. */
+    presence?: PresenceThrottleOptions;
+    /** Max scheduled messages dispatched per second, smoothing backlog bursts. Default `1`; `0` disables. */
+    scheduleRateLimitPerSec?: number;
 }
 type ConnectionEventMap = {
     connect: {
@@ -867,6 +972,12 @@ type ConnectionEventMap = {
         delayMs: number;
         reason: DisconnectReasonDomain;
     };
+    'auth-exhausted': {
+        sessionId: string;
+        kind: ConnectionAuthType;
+        attempts: number;
+        max: number;
+    };
     error: {
         sessionId: string;
         error: Error;
@@ -983,22 +1094,6 @@ type BroadcastDeps = {
 };
 declare function runBroadcast(jids: string[], build: (b: MessageBuilder<'init'>) => MessageBuilder<'content-set'>, deps: BroadcastDeps, options?: BroadcastOptions): Promise<BroadcastResult>;
 
-type WAPresence = 'unavailable' | 'available' | 'composing' | 'recording' | 'paused';
-interface AutomationSocketLike {
-    sendPresenceUpdate(type: WAPresence, toJid?: string): Promise<void>;
-}
-declare class PresenceModule {
-    private readonly getSocket;
-    constructor(getSocket: () => AutomationSocketLike | undefined);
-    protected requireSocket(): AutomationSocketLike;
-    private update;
-    private scheduleClear;
-    online(): Promise<void>;
-    offline(): Promise<void>;
-    typing(jid: string, ms?: number): Promise<void>;
-    recording(jid: string, ms?: number): Promise<void>;
-}
-
 type ScheduledContentSnapshot = {
     recipient: string;
     content: AnyMessageContent;
@@ -1014,6 +1109,7 @@ type SchedulerDeps = {
     now?: () => number;
     timer?: SchedulerTimer;
     logger?: Logger;
+    acquire?: () => Promise<void>;
 };
 type ScheduleHandle = {
     id: string;
@@ -1025,6 +1121,7 @@ declare class Scheduler {
     private readonly now;
     private readonly timer;
     private readonly logger;
+    private readonly acquire;
     private readonly memory;
     private readonly timers;
     constructor(deps: SchedulerDeps);
@@ -1072,6 +1169,11 @@ declare class Client extends TypedEventEmitter<ClientEventMap> {
     private readonly baileysExtra;
     private readonly machine;
     private reconnectStrategy;
+    private readonly authGuard;
+    private readonly operationGuard;
+    private readonly presenceThrottle;
+    private readonly scheduleLimiter;
+    private authExhausted;
     private _socket;
     private reconnectTimer;
     private listenerCleanup;
@@ -1137,7 +1239,9 @@ declare class Client extends TypedEventEmitter<ClientEventMap> {
     private wireSocket;
     private handleConnectionUpdate;
     private handleQrUpdate;
+    private handleAuthExhausted;
     private handleOpen;
+    private resolveMessageForResend;
     private lookupQuoted;
     private handleClose;
     private rejectPendingConnect;
@@ -1258,8 +1362,6 @@ interface CacheableAuthStoreOptions {
         warn?: (msg: unknown) => void;
         error?: (msg: unknown) => void;
     };
-    cacheSize?: number;
-    cacheTtlSeconds?: number;
 }
 declare function makeCacheableAuthStore(bundle: AuthStoreBundle, options?: CacheableAuthStoreOptions): AuthStoreBundle;
 
@@ -1670,4 +1772,4 @@ declare class Media {
     toBuffer(): Promise<Buffer>;
 }
 
-export { type AddressButton, type AlbumItem, type AudioOptions, AudioProcessor, type AudioType, type AuthCredsStore, type AuthStore, type AuthStoreBundle, type AuthStoreKey, type AuthStoreValue, type AutomationErrorCode, type AutomationSocketLike, type BaileysSocket, type BaileysSocketLike, type BottomSheetOptions, type BroadcastDeps, type BroadcastOptions, type BroadcastResult, BufferConverter, type BuildContextInput, type BuilderContext, type BuilderErrorCode, type BuilderSocketLike, type BuilderState, type ButtonClickPayload, type ButtonDef, type CacheableAuthStoreOptions, type CallBase, type CallButton, type CallPayload, type CancelReminderButton, type ChatType, type CitationConfig, type CitationPredicates, Client, type ClientEventMap, type ClientEventName, type ClientOptions, type CommandContext, type CommandDefinition, type CommandErrorCode, type CommandHandler, type CommandPrefix, CommandRegistry, CommunityModule, type ConnectionAuthType, type ConnectionEventHandler, type ConnectionEventMap, type ConnectionEventName, type ConnectionState, type ConnectionStateMachine, type ContextMedia, ConvexAuthStore, type ConvexAuthStoreOptions, ConvexMessageStore, type ConvexMessageStoreOptions, type CopyButton, type CreateLoggerOptions, type DeleteOptions, type DeletePayload, type DisconnectReasonDomain, type DispatcherDeps, type DispatcherHandle, type DocumentOptions, DocumentProcessor, type DomainErrorCode, type DomainSocketLike, EditBuilder, type EditPayload, FFMPEG_CONSTANTS, type FFmpegConfig, FFmpegProcessor, FileAuthStore, type FileAuthStoreOptions, type FileExtension, FileManager, type GroupJoinPayload, type GroupLeavePayload, GroupModule, type GroupParticipantInfo, type GroupUpdatePayload, type HistorySyncPayload, type ImageOptions, ImageProcessor, type InboundEventMap, type InboundEventName, type InteractiveButton, type LIDMapping, type LIDMappingUpdatePayload, type LimitedPayload, type LimitedTimeOfferOptions, type LinkedGroup, type ListOptions, type ListSection, type ListSelectPayload, type LocationOptions, type LocationRequestButton, type Logger, type LoggerLevel, Media, type MediaDescriptor, type MediaDownloadResult, type MediaInput, type MediaKind, type MediaSource, type MemberTagPayload, MemoryAuthStore, MemoryMessageStore, type MentionAllContext, type MentionContext, MessageBuilder, type MessageContext, type MessageStore, type MessageStoreListOptions, type Middleware, MimeValidator, NewsletterModule, type NewsletterPayload, type PairingFlow, type PairingFlowOptions, type PairingFlowResult, type ParsedArgs, type ParticipantUpdateResult, type PollOptions, type PollVotePayload, PostgresAuthStore, type PostgresAuthStoreOptions, PostgresMessageStore, type PostgresMessageStoreOptions, PresenceModule, type PresencePayload, type PrivacyConfig, PrivacyModule, type PrivacySettings, type QuotedRef, RateLimiter, type RateLimiterClock, type RateLimiterOptions, type ReactionPayload, type ReconnectDecision, type ReconnectOptions, type ReconnectStrategy, type ReconnectStrategyDeps, RedisAuthStore, type RedisAuthStoreOptions, RedisMessageStore, type RedisMessageStoreOptions, type ReminderButton, type ReplyButton, type ResolvedCommand, type RetryPolicy, SELF_ONLY_PROTOCOL_TYPES, type ScheduleHandle, type ScheduledContentSnapshot, type ScheduledJob, type ScheduledJobRecord, Scheduler, type SchedulerDeps, type SchedulerTimer, type SelfOnlyProtocolType, type SenderDevice, type SenderInfo, SqliteAuthStore, type SqliteAuthStoreOptions, SqliteMessageStore, type SqliteMessageStoreOptions, type StateTransitionListener, type StickerMetadataType, type StickerOptions, StickerProcessor, type StickerShapeType, type StoreErrorCode, TaskQueue, type TaskQueueClock, type TaskQueueOptions, type TemplateOptions, type TextOptions, TypedEventEmitter, type TypedEventEmitterOptions, type UpsertPayload, type UrlButton, type UsernameResolveSocketLike, type VideoOptions, VideoProcessor, type WAPresence, ZaileysAutomationError, ZaileysBuilderError, ZaileysCommandError, ZaileysDomainError, type ZaileysLogger, ZaileysStoreError, adoptLogger, attachCommandDispatcher, buildMessageContext, chunk, createConnectionStateMachine, createLogger, createPairingFlow, createReconnectStrategy, deleteMessage, detectFileType, dropSpoofedSelfOnly, ffmpegTransform, forwardMessage, generateId, initializeFFmpeg, isFatalDisconnect, isJid, makeCacheableAuthStore, mapDisconnectReason, normalizePhoneNumber, parseCommand, printQrToTerminal, reactToMessage, renderQrInTerminal, resolveUsername, runBroadcast, runMiddleware, shouldClearAuth, shouldReconnect, signalKeyStoreFromAuthStore, validateE164 };
+export { type AddressButton, type AlbumItem, type AudioOptions, AudioProcessor, type AudioType, type AuthAttemptBlockReason, type AuthAttemptDecision, type AuthCredsStore, type AuthGuard, type AuthGuardOptions, type AuthStore, type AuthStoreBundle, type AuthStoreKey, type AuthStoreValue, type AutomationErrorCode, type AutomationSocketLike, type BaileysSocket, type BaileysSocketLike, type BottomSheetOptions, type BroadcastDeps, type BroadcastOptions, type BroadcastResult, BufferConverter, type BuildContextInput, type BuilderContext, type BuilderErrorCode, type BuilderSocketLike, type BuilderState, type ButtonClickPayload, type ButtonDef, type CacheableAuthStoreOptions, type CallBase, type CallButton, type CallPayload, type CancelReminderButton, type ChatType, type CitationConfig, type CitationPredicates, Client, type ClientEventMap, type ClientEventName, type ClientOptions, type CommandContext, type CommandDefinition, type CommandErrorCode, type CommandHandler, type CommandPrefix, CommandRegistry, CommunityModule, type ConnectionAuthType, type ConnectionEventHandler, type ConnectionEventMap, type ConnectionEventName, type ConnectionState, type ConnectionStateMachine, type ContextMedia, ConvexAuthStore, type ConvexAuthStoreOptions, ConvexMessageStore, type ConvexMessageStoreOptions, type CopyButton, type CreateLoggerOptions, type DeleteOptions, type DeletePayload, type DisconnectReasonDomain, type DispatcherDeps, type DispatcherHandle, type DocumentOptions, DocumentProcessor, type DomainErrorCode, type DomainSocketLike, EditBuilder, type EditPayload, FFMPEG_CONSTANTS, type FFmpegConfig, FFmpegProcessor, FileAuthStore, type FileAuthStoreOptions, type FileExtension, FileManager, type GroupJoinPayload, type GroupLeavePayload, GroupModule, type GroupParticipantInfo, type GroupUpdatePayload, type HistorySyncPayload, type ImageOptions, ImageProcessor, type InboundEventMap, type InboundEventName, type InteractiveButton, type LIDMapping, type LIDMappingUpdatePayload, type LimitedPayload, type LimitedTimeOfferOptions, type LinkedGroup, type ListOptions, type ListSection, type ListSelectPayload, type LocationOptions, type LocationRequestButton, type Logger, type LoggerLevel, Media, type MediaDescriptor, type MediaDownloadResult, type MediaInput, type MediaKind, type MediaSource, type MemberTagPayload, MemoryAuthStore, MemoryMessageStore, type MentionAllContext, type MentionContext, MessageBuilder, type MessageContext, type MessageStore, type MessageStoreListOptions, type Middleware, MimeValidator, NewsletterModule, type NewsletterPayload, type OperationCategory, type OperationGuard, type OperationGuardClock, type OperationGuardOptions, type PairingFlow, type PairingFlowOptions, type PairingFlowResult, type ParsedArgs, type ParticipantUpdateResult, type PollOptions, type PollVotePayload, PostgresAuthStore, type PostgresAuthStoreOptions, PostgresMessageStore, type PostgresMessageStoreOptions, type PresenceClock, PresenceModule, type PresencePayload, type PresenceThrottleOptions, type PrivacyConfig, PrivacyModule, type PrivacySettings, type QuotedRef, RateLimiter, type RateLimiterClock, type RateLimiterOptions, type ReactionPayload, type ReconnectDecision, type ReconnectOptions, type ReconnectStrategy, type ReconnectStrategyDeps, RedisAuthStore, type RedisAuthStoreOptions, RedisMessageStore, type RedisMessageStoreOptions, type ReminderButton, type ReplyButton, type ResolvedCommand, type RetryPolicy, SELF_ONLY_PROTOCOL_TYPES, type ScheduleHandle, type ScheduledContentSnapshot, type ScheduledJob, type ScheduledJobRecord, Scheduler, type SchedulerDeps, type SchedulerTimer, type SelfOnlyProtocolType, type SenderDevice, type SenderInfo, SqliteAuthStore, type SqliteAuthStoreOptions, SqliteMessageStore, type SqliteMessageStoreOptions, type StateTransitionListener, type StickerMetadataType, type StickerOptions, StickerProcessor, type StickerShapeType, type StoreErrorCode, TaskQueue, type TaskQueueClock, type TaskQueueOptions, type TemplateOptions, type TextOptions, TypedEventEmitter, type TypedEventEmitterOptions, type UpsertPayload, type UrlButton, type UsernameResolveSocketLike, type VideoOptions, VideoProcessor, type WAPresence, ZaileysAutomationError, ZaileysBuilderError, ZaileysCommandError, ZaileysDomainError, type ZaileysLogger, ZaileysStoreError, adoptLogger, attachCommandDispatcher, buildMessageContext, chunk, createAuthGuard, createConnectionStateMachine, createLogger, createOperationGuard, createPairingFlow, createReconnectStrategy, deleteMessage, detectFileType, dropSpoofedSelfOnly, ffmpegTransform, forwardMessage, generateId, initializeFFmpeg, isFatalDisconnect, isJid, isRateLimited, makeCacheableAuthStore, mapDisconnectReason, normalizePhoneNumber, parseCommand, printQrToTerminal, reactToMessage, renderQrInTerminal, resolveUsername, runBroadcast, runMiddleware, shouldClearAuth, shouldReconnect, signalKeyStoreFromAuthStore, validateE164 };