@violetix/baileys 0.3.18 → 0.5.0

package/lib/Socket/socket.js

@@ -7,6 +7,8 @@ import { DEF_CALLBACK_PREFIX, DEF_TAG_PREFIX, INITIAL_PREKEY_COUNT, MIN_PREKEY_C
 import { QueryIds, ReachoutTimelockEnforcementType } from '../Types/index.js';
 import { DisconnectReason, XWAPaths } from '../Types/index.js';
 import { addTransactionCapability, aesEncryptCTR, bindWaitForConnectionUpdate, buildPairingQRData, bytesToCrockford, configureSuccessfulPairing, Curve, derivePairingCodeKey, fetchLatestWaWebVersion, generateLoginNode, generateMdTagPrefix, generateRegistrationNode, getCodeFromWSError, getErrorCodeFromStreamError, getNextPreKeysNode, getPairingCodePlatform, invalidPairingCodeChars, makeEventBuffer, makeNoiseHandler, normalizePairingCode, PAIRING_CODE_ALPHABET, promiseTimeout, signedKeyPair, xmppSignedPreKey } from '../Utils/index.js';
+import { ignoredStanzaNeedsAck, makeIgnoreKeyRegistry } from '../Utils/ignore-key.js';
+import { buildAckStanza } from '../Utils/stanza-ack.js';
 import { assertNodeErrorFree, binaryNodeToString, encodeBinaryNode, getAllBinaryNodeChildren, getBinaryNodeChild, getBinaryNodeChildren, isLidUser, jidDecode, jidEncode, S_WHATSAPP_NET } from '../WABinary/index.js';
 import { BinaryInfo } from '../WAM/BinaryInfo.js';
 import { USyncQuery, USyncUser } from '../WAUSync/index.js';
@@ -134,12 +136,13 @@ export const makeSocket = (config) => {
             node.attrs.id = generateMessageTag();
         }
         const msgId = node.attrs.id;
+        pendingQueries++;
         const result = await promiseTimeout(timeoutMs, async (resolve, reject) => {
             const result = waitForMessage(msgId, timeoutMs).catch(reject);
             sendNode(node)
                 .then(async () => resolve(await result))
                 .catch(reject);
-        });
+        }).finally(() => { pendingQueries--; });
         if (result && 'tag' in result) {
             assertNodeErrorFree(result);
         }
@@ -374,6 +377,8 @@ export const makeSocket = (config) => {
     const keys = addTransactionCapability(authState.keys, logger, transactionOpts);
     const signalRepository = makeSignalRepository({ creds, keys }, logger, pnFromLIDUSync);
     let lastDateRecv;
+    /** queries awaiting a reply; keep-alive skips its ping while these are flowing */
+    let pendingQueries = 0;
     let epoch = 1;
     let keepAliveReq;
     let qrTimer;
@@ -560,6 +565,11 @@ export const makeSocket = (config) => {
             // Don't throw - allow connection to continue even if pre-key check fails
         }
     };
+    const ignoreKeyRegistry = makeIgnoreKeyRegistry({
+        getMeId: () => authState.creds.me?.id,
+        getMeLid: () => authState.creds.me?.lid,
+        logger
+    });
     const onMessageReceived = async (data) => {
         await noise.decodeFrame(data, frame => {
             lastDateRecv = new Date();
@@ -570,6 +580,16 @@ export const makeSocket = (config) => {
                 if (logger.level === 'trace') {
                     logger.trace({ xml: binaryNodeToString(frame), msg: 'recv xml' });
                 }
+                // Filters run before every other handler, so a dropped stanza never reaches the
+                // decryption or persistence paths. The ack still goes out, otherwise the server
+                // keeps re-delivering what the host just asked to ignore.
+                if (ignoreKeyRegistry.shouldDrop(frame)) {
+                    logger.debug({ tag: frame.tag, id: msgId, from: frame.attrs.from }, 'stanza dropped by ignoreKey');
+                    if (ignoredStanzaNeedsAck(frame.tag)) {
+                        sendNode(buildAckStanza(frame, undefined, authState.creds.me?.id)).catch(err => logger.error({ err, id: msgId }, 'failed to ack ignored stanza'));
+                    }
+                    return;
+                }
                 anyTriggered = ws.emit(`${DEF_TAG_PREFIX}${msgId}`, frame) || anyTriggered;
                 const l0 = frame.tag;
                 const l1 = frame.attrs || {};
@@ -694,48 +714,89 @@ export const makeSocket = (config) => {
             ws.off('error', onClose);
         });
     };
+    /**
+     * Keep-alive, modelled on zapo-js (src/transport/keepalive/WaKeepAlive.ts):
+     * - self-rescheduling setTimeout with +-10% jitter (min 250ms), so a fleet of sockets in one
+     *   process drifts apart instead of pinging in the same tick
+     * - at most one ping in flight; a slow pong never stacks more pings on a busy loop
+     * - no ping while other queries are pending and data arrived recently: the link is
+     *   demonstrably alive and the ping would only add queue pressure
+     * - "lost" is still decided by inbound silence (interval + grace), and skipped when the
+     *   timer itself fired late (blocked event loop: pongs may be unread in the socket buffer)
+     */
     const startKeepAliveRequest = () => {
+        let timer;
+        let stopped = false;
+        let pingInFlight = false;
+        let lastCheckAt;
+        let expectedDelayMs = 0;
+        const nextDelay = () => {
+            const jitter = Math.max(250, Math.floor(keepAliveIntervalMs * 0.1));
+            return Math.max(1000, keepAliveIntervalMs + Math.floor((Math.random() * 2 - 1) * jitter));
+        };
+        const schedule = (delayMs) => {
+            if (stopped) {
+                return;
+            }
+            expectedDelayMs = delayMs;
+            timer = safeSetTimeout(() => {
+                timer = undefined;
+                cb();
+                schedule(nextDelay());
+            }, delayMs);
+        };
         const cb = () => {
             if (!lastDateRecv) {
                 lastDateRecv = new Date();
             }
-            const diff = Date.now() - lastDateRecv.getTime();
-            if (diff > keepAliveIntervalMs + keepAliveGracePeriodMs) {
-                void end(new Boom('Connection was lost', { statusCode: DisconnectReason.connectionLost }));
+            const now = Date.now();
+            const sinceRecvMs = now - lastDateRecv.getTime();
+            const lagMs = lastCheckAt ? now - lastCheckAt - expectedDelayMs : 0;
+            lastCheckAt = now;
+            const loopStalled = lagMs > keepAliveGracePeriodMs;
+            if (loopStalled) {
+                logger.warn({ lagMs, sinceLastRecvMs: sinceRecvMs }, 'event loop stalled; deferring keep-alive timeout');
             }
-            else if (ws.isOpen) {
-                query({
-                    tag: 'iq',
-                    attrs: {
-                        id: generateMessageTag(),
-                        to: S_WHATSAPP_NET,
-                        type: 'get',
-                        xmlns: 'w:p'
-                    },
-                    content: [{ tag: 'ping', attrs: {} }]
-                }).catch(err => {
-                    logger.error({ trace: err.stack }, 'error in sending keep alive');
-                });
+            if (sinceRecvMs > keepAliveIntervalMs + keepAliveGracePeriodMs && !loopStalled) {
+                void end(new Boom('Connection was lost', { statusCode: DisconnectReason.connectionLost }));
+                return;
             }
-            else {
+            if (!ws.isOpen) {
                 logger.warn('keep alive called when WS not open');
+                return;
+            }
+            if (pingInFlight) {
+                logger.trace('keep alive skipped: ping already in flight');
+                return;
             }
+            if (pendingQueries > 0 && sinceRecvMs < keepAliveGracePeriodMs) {
+                logger.trace({ pendingQueries, sinceRecvMs }, 'keep alive skipped: queries pending with recent inbound');
+                return;
+            }
+            pingInFlight = true;
+            query({
+                tag: 'iq',
+                attrs: {
+                    id: generateMessageTag(),
+                    to: S_WHATSAPP_NET,
+                    type: 'get',
+                    xmlns: 'w:p'
+                },
+                content: [{ tag: 'ping', attrs: {} }]
+            }, keepAliveIntervalMs + keepAliveGracePeriodMs)
+                .catch(err => {
+                    // the verdict stays with inbound silence above; a failed ping alone is not "lost"
+                    logger.warn({ trace: err.stack }, 'error in sending keep alive');
+                })
+                .finally(() => { pingInFlight = false; });
         };
-        // Per socket, so keepAliveIntervalMs from the config is actually the ping interval: the
-        // shared process-wide timer ran at a hardcoded 30s while the staleness check below still
-        // used the configured value, so any interval other than 30s produced false connectionLost.
-        // The random start offset staggers the fleet - on the shared timer every socket in the
-        // process pinged in the same tick, which is a self-inflicted burst at 100+ sessions.
-        let pinger;
-        const starter = safeSetTimeout(() => {
-            cb();
-            pinger = safeSetInterval(cb, keepAliveIntervalMs);
-        }, Math.floor(Math.random() * (keepAliveIntervalMs / 2)));
+        // random first tick staggers sockets that connect together (reconnect storms)
+        schedule(Math.floor(Math.random() * (keepAliveIntervalMs / 2)));
         keepAliveReq = {
             cb,
             cancel: () => {
-                clearSafeTimer(starter);
-                clearSafeTimer(pinger);
+                stopped = true;
+                clearSafeTimer(timer);
             }
         };
     };
@@ -1227,6 +1288,7 @@ export const makeSocket = (config) => {
             return authState.creds.me;
         },
         generateMessageTag,
+        ignoreKey: ignoreKeyRegistry.register,
         query,
         waitForMessage,
         waitForSocketOpen,

package/lib/Store/make-in-memory-store.js

@@ -9,7 +9,7 @@ import { writeFileSync, readFileSync, existsSync } from 'fs';
 import { WAProto } from '../Types/index.js';
 import { LabelAssociationType } from '../Types/LabelAssociation.js';
 import { DEFAULT_CONNECTION_CONFIG } from '../Defaults/index.js';
-import { md5, toNumber, updateMessageWithReceipt, updateMessageWithReaction } from '../Utils/index.js';
+import { BufferJSON, md5, toNumber, updateMessageWithReceipt, updateMessageWithReaction } from '../Utils/index.js';
 import { jidDecode, jidNormalizedUser } from '../WABinary/index.js';
 import { makeOrderedDictionary } from './make-ordered-dictionary.js';
 import { ObjectRepository } from './object-repository.js';
@@ -69,6 +69,9 @@ export const makeInMemoryStore = (config = {}) => {
             }
         }
     };
+    // one key rule for every handler; upsert used alt+normalized while update/receipt/reaction/delete
+    // used raw or non-alt keys, so LID chats never found their stored messages
+    const keyJid = (key) => jidNormalizedUser(key.remoteJidAlt || key.remoteJid);
     const assertMessageList = (jid) => {
         if (!messages[jid]) {
             messages[jid] = makeMessagesDictionary();
@@ -116,8 +119,7 @@ export const makeInMemoryStore = (config = {}) => {
             }
             logger.debug({ deletedContacts: isLatest ? oldContacts.size : 0, newContacts }, 'synced contacts');
             for (const msg of newMessages) {
-                const jid = msg.key.remoteJidAlt || msg.key.remoteJid;
-                const list = assertMessageList(jid);
+                const list = assertMessageList(keyJid(msg.key));
                 list.upsert(msg, 'prepend');
             }
             enforceLimits(messages, groupMetadata, chats, maxChats, maxMessagesPerChat);
@@ -149,9 +151,13 @@ export const makeInMemoryStore = (config = {}) => {
                     }
                 }
                 else {
-                    return logger.debug({ update }, 'got update for non-existant contact');
+                    logger.debug({ update }, 'got update for non-existant contact');
+                    continue;
                 }
-                Object.assign(contacts[contact.id], contact);
+                // was Object.assign(contact, contact): update fields (notify, name...) never landed.
+                // id may be a WA_ADD_NOTIF hash and imgUrl a sentinel, so neither is copied.
+                const { id: _id, imgUrl: _imgUrl, ...fields } = update;
+                Object.assign(contact, fields);
             }
         });
         on('chats.upsert', newChats => {
@@ -211,7 +217,7 @@ export const makeInMemoryStore = (config = {}) => {
                 case 'append':
                 case 'notify':
                     for (const msg of newMessages) {
-                        const jid = jidNormalizedUser(msg.key.remoteJidAlt || msg.key.remoteJid);
+                        const jid = keyJid(msg.key);
                         const list = assertMessageList(jid);
                         list.upsert(msg, 'append');
                         enforceLimits(messages, groupMetadata, chats, maxChats, maxMessagesPerChat);
@@ -231,7 +237,12 @@ export const makeInMemoryStore = (config = {}) => {
         on('messages.update', updates => {
             var _a;
             for (const { update, key } of updates) {
-                const list = assertMessageList(jidNormalizedUser(key.remoteJid));
+                // no create: an update for an unknown chat must not add an empty list that evicts real ones
+                const list = messages[keyJid(key)];
+                if (!list) {
+                    logger.debug({ update }, 'got update for non-existent message');
+                    continue;
+                }
                 if (update === null || update === void 0 ? void 0 : update.status) {
                     const listStatus = (_a = list.get(key.id)) === null || _a === void 0 ? void 0 : _a.status;
                     if (listStatus && (update === null || update === void 0 ? void 0 : update.status) <= listStatus) {
@@ -252,8 +263,7 @@ export const makeInMemoryStore = (config = {}) => {
                 list === null || list === void 0 ? void 0 : list.clear();
             }
             else {
-                const jid = item.keys[0].remoteJidAlt || item.keys[0].remoteJid;
-                const list = messages[jid];
+                const list = messages[keyJid(item.keys[0])];
                 if (list) {
                     const idSet = new Set(item.keys.map(k => k.id));
                     list.filter(m => !idSet.has(m.key.id));
@@ -308,8 +318,7 @@ export const makeInMemoryStore = (config = {}) => {
         });
         on('message-receipt.update', updates => {
             for (const { key, receipt } of updates) {
-                const obj = messages[key.remoteJidAlt || key.remoteJid];
-                const msg = obj === null || obj === void 0 ? void 0 : obj.get(key.id);
+                const msg = messages[keyJid(key)]?.get(key.id);
                 if (msg) {
                     updateMessageWithReceipt(msg, receipt);
                 }
@@ -317,8 +326,7 @@ export const makeInMemoryStore = (config = {}) => {
         });
         on('messages.reaction', (reactions) => {
             for (const { key, reaction } of reactions) {
-                const obj = messages[key.remoteJidAlt || key.remoteJid];
-                const msg = obj === null || obj === void 0 ? void 0 : obj.get(key.id);
+                const msg = messages[keyJid(key)]?.get(key.id);
                 if (msg) {
                     updateMessageWithReaction(msg, reaction);
                 }
@@ -363,28 +371,28 @@ export const makeInMemoryStore = (config = {}) => {
         bind,
         /** loads messages from the store, if not found -- uses the legacy connection */
         loadMessages: async (jid, count, cursor) => {
-            const list = assertMessageList(jid);
+            const list = messages[jid]; // read-only: don't create phantom lists
             const mode = !cursor || 'before' in cursor ? 'before' : 'after';
             const cursorKey = !!cursor ? ('before' in cursor ? cursor.before : cursor.after) : undefined;
-            const cursorValue = cursorKey ? list.get(cursorKey.id) : undefined;
-            let messages;
+            const cursorValue = cursorKey ? list?.get(cursorKey.id) : undefined;
+            let result;
             if (list && mode === 'before' && (!cursorKey || cursorValue)) {
                 if (cursorValue) {
                     const msgIdx = list.array.findIndex(m => m.key.id === (cursorKey === null || cursorKey === void 0 ? void 0 : cursorKey.id));
-                    messages = list.array.slice(0, msgIdx);
+                    result = list.array.slice(0, msgIdx);
                 }
                 else {
-                    messages = list.array;
+                    result = list.array;
                 }
-                const diff = count - messages.length;
+                const diff = count - result.length;
                 if (diff < 0) {
-                    messages = messages.slice(-count); // get the last X messages
+                    result = result.slice(-count); // get the last X messages
                 }
             }
             else {
-                messages = [];
+                result = [];
             }
-            return messages;
+            return result;
         },
         /**
          * Get all available labels for profile
@@ -447,13 +455,13 @@ export const makeInMemoryStore = (config = {}) => {
         toJSON,
         fromJSON,
         writeToFile: (path) => {
-            writeFileSync(path, JSON.stringify(toJSON()));
+            writeFileSync(path, JSON.stringify(toJSON(), BufferJSON.replacer));
         },
         readFromFile: (path) => {
             if (existsSync(path)) {
                 logger.debug({ path }, 'reading from file');
                 const jsonStr = readFileSync(path, { encoding: 'utf-8' });
-                const json = JSON.parse(jsonStr);
+                const json = JSON.parse(jsonStr, BufferJSON.reviver);
                 fromJSON(json);
             }
         }

package/lib/Utils/a2ui.d.ts

@@ -0,0 +1,50 @@
+export type A2UIWidget = {
+    uuid: string;
+    data: string;
+    type: string;
+    fallback?: string;
+};
+export type A2UIBuildOptions = {
+    uuid?: string;
+    surfaceId?: string;
+    type?: string;
+    /** `false` emits a bare `{ components }` payload instead of the `createSurface` envelope. */
+    wrapped?: boolean;
+};
+export type A2UIChoice = {
+    label: string;
+    value: unknown;
+};
+export type A2UIListCardItem = {
+    title: string;
+    price?: string;
+    trailingLabel?: string;
+    assetId?: string;
+    assetType?: string;
+    emphasis?: string;
+};
+/** Every method registers a component and returns its id; container methods take those ids. */
+export declare class A2UI {
+    constructor(options?: { catalogId?: string; version?: string });
+    text(text: string, options?: { id?: string; variant?: string }): string;
+    image(url: string, options?: { id?: string; variant?: string; fit?: string }): string;
+    video(url: string, options?: { id?: string }): string;
+    checkbox(label: string, options?: { id?: string; value?: boolean }): string;
+    textField(label: string, options?: { id?: string; variant?: string }): string;
+    button(childId: string, options?: { id?: string; variant?: string; action?: any }): string;
+    card(childId: string, options?: { id?: string }): string;
+    column(children: string[], options?: { id?: string; justify?: string; align?: string }): string;
+    row(children: string[], options?: { id?: string }): string;
+    divider(options?: { id?: string }): string;
+    choicePicker(label: string, options: A2UIChoice[], extra?: {
+        id?: string;
+        variant?: string;
+        value?: unknown;
+        displayStyle?: string;
+        filterable?: boolean;
+    }): string;
+    root(children: string[]): this;
+    listCard(input: { title: string; items: A2UIListCardItem[]; fallbackText?: string; uuid?: string }): this;
+    build(options?: A2UIBuildOptions): A2UIWidget;
+}
+export declare const buildA2UIWidget: (a2ui: A2UI | A2UIWidget, options?: A2UIBuildOptions) => A2UIWidget;

package/lib/Utils/a2ui.js

@@ -0,0 +1,168 @@
+// A2UI (Agent-to-UI) widget builder. Declarative components — Text, Image, Video, Button,
+// Card, Column, Row, Divider, CheckBox, TextField, ChoicePicker, plus the `listCard` shortcut
+// — compiled into the JSON payload WhatsApp carries in `interactiveMessage.bloksWidget`.
+//
+// Ported from @rennzsync/baileys (MIT).
+//
+// Every builder method registers a component and returns its id; ids are what the container
+// methods take, so a tree is written bottom-up:
+//
+//     const ui = new A2UI()
+//     const title = ui.text('Hello', { variant: 'h1' })
+//     const button = ui.button(ui.text('Press me'), { action: { name: 'noop' } })
+//     ui.root([ui.card(ui.column([title, button]))])
+//     await sock.sendMessage(jid, { a2ui: ui, text: 'Widget' })
+//
+// This is an internal WhatsApp format: a send can succeed while the recipient's client renders
+// nothing. Verify against your target client build before relying on it.
+import { randomUUID } from 'crypto';
+const DEFAULT_CATALOG_ID = 'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json';
+export class A2UI {
+    constructor({ catalogId = DEFAULT_CATALOG_ID, version = 'v0.9' } = {}) {
+        this._version = version;
+        this._catalogId = catalogId;
+        this._components = new Map();
+        this._counter = 0;
+        this._rootChildren = [];
+        this._listCardPayload = undefined;
+    }
+    #nextId(prefix) {
+        return `${prefix}_${(this._counter++).toString(36)}`;
+    }
+    #reg(id, component, extra = {}) {
+        id ??= this.#nextId(component.toLowerCase());
+        if (this._components.has(id)) {
+            throw new Error(`Component id "${id}" already used`);
+        }
+        this._components.set(id, { id, component, ...extra });
+        return id;
+    }
+    text(text, { id, variant = 'body' } = {}) {
+        return this.#reg(id, 'Text', { text, variant });
+    }
+    image(url, { id, variant, fit = 'cover' } = {}) {
+        return this.#reg(id, 'Image', { url, ...(variant ? { variant } : {}), fit });
+    }
+    video(url, { id } = {}) {
+        return this.#reg(id, 'Video', { url });
+    }
+    checkbox(label, { id, value = false } = {}) {
+        return this.#reg(id, 'CheckBox', { label, value });
+    }
+    textField(label, { id, variant = 'text' } = {}) {
+        return this.#reg(id, 'TextField', { label, variant });
+    }
+    button(childId, { id, variant = 'primary', action } = {}) {
+        if (!childId) {
+            throw new TypeError('button(childId) requires the id of a child component (e.g. from .text())');
+        }
+        return this.#reg(id, 'Button', { child: childId, variant, ...(action ? { action } : {}) });
+    }
+    card(childId, { id } = {}) {
+        if (!childId) {
+            throw new TypeError('card(childId) requires the id of a child component');
+        }
+        return this.#reg(id, 'Card', { child: childId });
+    }
+    column(children = [], { id, justify, align } = {}) {
+        if (!children.length) {
+            throw new TypeError('column(children) requires at least one child id');
+        }
+        return this.#reg(id, 'Column', { children, ...(justify ? { justify } : {}), ...(align ? { align } : {}) });
+    }
+    row(children = [], { id } = {}) {
+        if (!children.length) {
+            throw new TypeError('row(children) requires at least one child id');
+        }
+        return this.#reg(id, 'Row', { children });
+    }
+    divider({ id } = {}) {
+        return this.#reg(id, 'Divider', {});
+    }
+    choicePicker(label, options, { id, variant = 'mutuallyExclusive', value, displayStyle = 'checkbox', filterable = false } = {}) {
+        if (!Array.isArray(options) || !options.length) {
+            throw new TypeError('choicePicker(label, options) requires a non-empty options array of {label, value}');
+        }
+        return this.#reg(id, 'ChoicePicker', {
+            label,
+            variant,
+            ...(value !== undefined ? { value } : {}),
+            options,
+            displayStyle,
+            filterable
+        });
+    }
+    /** Names the top-level components. Required before `build()` unless `listCard` was used. */
+    root(children) {
+        if (!Array.isArray(children) || !children.length) {
+            throw new TypeError('root(children) requires a non-empty array of top-level component ids');
+        }
+        this._rootChildren = children;
+        return this;
+    }
+    /**
+     * Shortcut for the product-list widget, which uses its own payload shape rather than the
+     * component catalog. It replaces whatever the component methods built — `build()` returns
+     * this payload and ignores `root()`.
+     */
+    listCard({ title, items, fallbackText, uuid = randomUUID() } = {}) {
+        if (!title) {
+            throw new TypeError('listCard requires a title');
+        }
+        if (!Array.isArray(items) || !items.length) {
+            throw new TypeError('listCard requires a non-empty items array');
+        }
+        this._listCardPayload = {
+            uuid,
+            data: JSON.stringify({
+                type: 'list_card',
+                title,
+                fallback_text: fallbackText ?? '',
+                items: items.map(item => ({
+                    asset_id: item.assetId ?? randomUUID().replace(/-/g, '').slice(0, 17),
+                    asset_type: item.assetType ?? 'PRODUCT_ITEM',
+                    title: item.title,
+                    trailing_label: item.price ?? item.trailingLabel ?? '',
+                    trailing_emphasis: item.emphasis ?? 'strong'
+                }))
+            }),
+            type: 'im_a2ui',
+            fallback: fallbackText ?? ''
+        };
+        return this;
+    }
+    /** Compiles the tree into the `bloksWidget` payload. Called for you by `sendMessage`. */
+    build({ uuid = randomUUID(), surfaceId, type = 'im_a2ui', wrapped = true } = {}) {
+        if (this._listCardPayload) {
+            return this._listCardPayload;
+        }
+        if (!this._rootChildren.length) {
+            throw new Error('Call root([...ids]) before build()');
+        }
+        const root = { id: 'root', component: 'Column', children: this._rootChildren };
+        const components = [root, ...this._components.values()];
+        const data = wrapped
+            ? {
+                version: this._version,
+                createSurface: {
+                    surfaceId: surfaceId ?? `starcore-widget=${uuid}`,
+                    catalogId: this._catalogId,
+                    components
+                }
+            }
+            : { components };
+        return {
+            uuid,
+            data: JSON.stringify(data),
+            type
+        };
+    }
+}
+/** Accepts an `A2UI` instance or an already-built payload, and returns the payload. */
+export const buildA2UIWidget = (a2ui, options = {}) => {
+    const widget = typeof a2ui?.build === 'function' ? a2ui.build(options) : a2ui;
+    if (!widget || typeof widget.data !== 'string') {
+        throw new TypeError('a2ui must be an A2UI instance or a built widget payload with a `data` string');
+    }
+    return widget;
+};

package/lib/Utils/anchor-guard.d.ts

@@ -0,0 +1,71 @@
+export type AnchorGuardLimits = {
+    maxText: number;
+    maxCaption: number;
+    maxMentions: number;
+    maxGroupMentions: number;
+    maxButtons: number;
+    maxSections: number;
+    maxRows: number;
+    maxCards: number;
+    maxDepth: number;
+    maxNodes: number;
+    maxBytes: number;
+    maxParamsJson: number;
+    maxInvisibleRun: number;
+    maxCombiningRun: number;
+    maxNewlines: number;
+};
+export declare const ANCHORGUARD_DEFAULTS: AnchorGuardLimits;
+export type AnchorGuardDetectOptions = Partial<AnchorGuardLimits> & {
+    /** Pre-computed encoded size, checked against `maxBytes` without re-encoding. */
+    byteLength?: number;
+    /** Pass the `proto` namespace to also measure the encoded size. Costs an encode per check. */
+    proto?: any;
+};
+export type AnchorGuardDetectResult = {
+    flagged: boolean;
+    reasons: string[];
+};
+export declare const detectBug: (message: any, options?: AnchorGuardDetectOptions) => AnchorGuardDetectResult;
+export type AnchorGuardDetection = {
+    direction: 'incoming' | 'outgoing' | 'group-add';
+    jid?: string;
+    sender?: string;
+    message?: any;
+    content?: any;
+    reasons: string[];
+    burst?: boolean;
+};
+export type AnchorGuardOptions = {
+    /** Delete a flagged inbound message. Default `true`. */
+    autoDelete?: boolean;
+    /** `'auto'` revokes own messages and deletes others locally. Default `'auto'`. */
+    deleteMode?: 'auto' | 'everyone' | 'me';
+    /** Guard `messages.upsert`. Default `true`. */
+    guardIncoming?: boolean;
+    /** Wrap `sock.sendMessage` and reject crash payloads. Default `false`. */
+    guardOutgoing?: boolean;
+    /** Block the sender of a flagged message. Default `false`. */
+    blockOnBug?: boolean;
+    /** Only guard own chats. Default `false`. */
+    selfOnly?: boolean;
+    thresholds?: Partial<AnchorGuardLimits>;
+    onDetect?: (detection: AnchorGuardDetection) => void | Promise<void>;
+    proto?: any;
+    /** Messages from one sender inside `burstWindowMs` before it counts as a burst. `0` disables. */
+    burstThreshold?: number;
+    burstWindowMs?: number;
+    /** Remove the sender from the group on burst. Needs admin. Default `false`. */
+    kickOnBurst?: boolean;
+    /** Flag/kick when a burst-flagged inviter adds this account to a group. Default `false`. */
+    guardGroupAdds?: boolean;
+    /** Guard Meta AI's numbers instead of exempting them. Default `false`. */
+    metaAiNumbers?: boolean;
+    ownJid?: string;
+    logger?: any;
+};
+export declare const createAnchorGuard: (sock: any, options?: AnchorGuardOptions) => {
+    detect: (message: any) => AnchorGuardDetectResult;
+    stop: () => void;
+};
+export declare const createAntiBugGuard: typeof createAnchorGuard;