zapo-js 1.6.2 → 1.7.1

package/dist/esm/client/WaClient.js

@@ -1,11 +1,14 @@
 import { EventEmitter } from 'node:events';
 import { createIgnoreKeyFilter, validateIgnoreKey } from './messaging/ignore-key.js';
+import { createEphemeralObserver, persistIncomingEphemeralSetting } from './persistence/ephemeral-setting.js';
+import { runGroupHistoryBundle } from './persistence/group-history.js';
 import { runHistorySyncNotification } from './persistence/history-sync.js';
 import { persistIncomingMailboxEntities } from './persistence/mailbox.js';
 import { WriteBehindPersistence } from './persistence/WriteBehindPersistence.js';
 import { installWaClientPlugins } from './plugins/install.js';
 import { buildWaClientDependencies, resolveWaClientBase } from './WaClientFactory.js';
 import { ConsoleLogger } from '../infra/log/ConsoleLogger.js';
+import { unwrapMessage } from '../message/encode/content.js';
 import { proto } from '../proto.js';
 import { WA_DEFAULTS, WA_MESSAGE_TYPES } from '../protocol/constants.js';
 import { normalizeDeviceJid } from '../protocol/jid.js';
@@ -42,6 +45,10 @@ class WaClientImpl extends EventEmitter {
             threadStore: this.stores.threads,
             contactStore: this.stores.contacts
         }, this.logger, this.options.writeBehind);
+        this.observeEphemeralSetting = createEphemeralObserver({
+            logger: this.logger,
+            chatMetadataStore: this.stores.chatMetadata
+        });
         const dependencies = buildWaClientDependencies({
             base,
             runtime: {
@@ -182,6 +189,7 @@ class WaClientImpl extends EventEmitter {
         }
         try {
             this.emit('message', event);
+            this.observeEphemeralSetting(event);
             void persistIncomingMailboxEntities({
                 logger: this.logger,
                 writeBehind: this.writeBehind,
@@ -207,6 +215,9 @@ class WaClientImpl extends EventEmitter {
                     });
                 });
             }
+            if (this.options.history?.groupBundles === true && event.message && !event.key.fromMe) {
+                this.tryProcessGroupHistoryBundle(event);
+            }
             const protocolMessage = event.message?.protocolMessage;
             if (!protocolMessage) {
                 return;
@@ -258,6 +269,7 @@ class WaClientImpl extends EventEmitter {
                     await runHistorySyncNotification({
                         logger: this.logger,
                         mediaTransfer: this.mediaTransfer,
+                        chatMetadataStore: this.stores.chatMetadata,
                         writeBehind: this.writeBehind,
                         emitEvent: this.emit.bind(this),
                         onPrivacyTokens: (conversations) => this.deps.trustedContactToken.hydrateFromHistorySync(conversations),
@@ -270,6 +282,16 @@ class WaClientImpl extends EventEmitter {
                 }
                 return;
             }
+            if (protocolType === proto.Message.ProtocolMessage.Type.EPHEMERAL_SETTING) {
+                persistIncomingEphemeralSetting({
+                    logger: this.logger,
+                    writeBehind: this.writeBehind,
+                    chatMetadataStore: this.stores.chatMetadata,
+                    event,
+                    protocolMessage
+                });
+                return;
+            }
             if (SYNC_RELATED_PROTOCOL_TYPES.has(protocolType)) {
                 this.logger.info('incoming sync-related protocol message', {
                     id: event.key.id,
@@ -288,6 +310,43 @@ class WaClientImpl extends EventEmitter {
             this.leaveIncomingHandler();
         }
     }
+    /**
+     * Kicks off the group-history bundle download when the incoming message
+     * carries one. Fire-and-forget: the blob can be large, and the incoming
+     * handler must not stall behind a CDN fetch.
+     *
+     * The download outlives the handler that started it, so it takes a slot of
+     * its own in the drain accounting - `disconnect()` and `clearStoredState()`
+     * must not flush or wipe the stores while a bundle is still writing.
+     */
+    tryProcessGroupHistoryBundle(event) {
+        const bundle = unwrapMessage(event.message ?? {}).messageHistoryBundle;
+        const groupJid = event.key.remoteJid;
+        if (!bundle || !groupJid) {
+            return;
+        }
+        if (!this.tryEnterIncomingHandler()) {
+            return;
+        }
+        const credentials = this.deps.authClient.getCurrentCredentials();
+        void runGroupHistoryBundle({
+            logger: this.logger,
+            mediaTransfer: this.mediaTransfer,
+            writeBehind: this.writeBehind,
+            emitEvent: this.emit.bind(this),
+            meJid: credentials?.meJid,
+            meLid: credentials?.meLid,
+            getAbPropNumber: (name) => this.deps.abPropsCoordinator.getConfigValue(name)
+        }, {
+            bundle,
+            groupJid,
+            senderJid: event.key.participant ?? undefined,
+            bundleMessageId: event.key.id,
+            sentAtSeconds: event.timestampSeconds
+        }).finally(() => {
+            this.leaveIncomingHandler();
+        });
+    }
     async queryWithContext(context, node, timeoutMs = this.options.iqTimeoutMs ?? WA_DEFAULTS.IQ_TIMEOUT_MS, contextData = {}, options = {}) {
         return queryNodeWithContext(async (queryNode, queryTimeoutMs) => this.deps.lowLevelCoordinator.query(queryNode, queryTimeoutMs, options), this.logger, context, node, timeoutMs, contextData);
     }
@@ -362,6 +421,7 @@ class WaClientImpl extends EventEmitter {
      * your own backoff.
      */
     async disconnect() {
+        this.deps.privacyCoordinator.stopAccountSyncRefresh();
         await this.pauseIncomingEventsAndWaitDrain();
         const writeBehindFlush = await this.writeBehind.flush(this.options.writeBehind?.flushTimeoutMs);
         if (writeBehindFlush.remaining > 0) {

package/dist/esm/client/WaClientFactory.js

@@ -55,7 +55,7 @@ import { SignalProtocol } from '../signal/session/SignalProtocol.js';
 import { WaKeepAlive } from '../transport/keepalive/WaKeepAlive.js';
 import { buildAckNode } from '../transport/node/builders/global.js';
 import { buildPresenceNode } from '../transport/node/builders/presence.js';
-import { getFirstNodeChild } from '../transport/node/helpers.js';
+import { findNodeChild, getFirstNodeChild } from '../transport/node/helpers.js';
 import { createUsyncSidGenerator } from '../transport/node/usync.js';
 import { WaNodeOrchestrator } from '../transport/node/WaNodeOrchestrator.js';
 import { WaNodeTransport } from '../transport/node/WaNodeTransport.js';
@@ -96,6 +96,7 @@ export function resolveWaClientBase(options, logger) {
         sessionId,
         deviceBrowser: device.browser,
         deviceOsDisplayName: device.osDisplayName,
+        deviceOsVersion: device.osVersion ?? undefined,
         devicePlatform: device.platform,
         urls: options.urls ?? options.chatSocketUrls ?? WA_DEFAULTS.CHAT_SOCKET_URLS,
         iqTimeoutMs: options.iqTimeoutMs ?? WA_DEFAULTS.IQ_TIMEOUT_MS,
@@ -120,7 +121,7 @@ function createIncomingNodeRuntime(input) {
     const { logger, emitEvent, authClient, connectionManager, nodeOrchestrator, streamControl, mediaMessageBuildOptions, retryCoordinator, messageDispatch, sendNode, syncAppState, disconnect, clearStoredCredentials, getCurrentCredentials, handleClientDirtyBits, incomingMessageAckOptions } = input;
     return {
         handleStreamControlResult: streamControl.handleStreamControlResult,
-        persistSuccessAttributes: (attributes) => authClient.persistSuccessAttributes(attributes),
+        persistSuccessAttributes: (attributes) => authClient.persistSuccessAttributes(attributes, { countsAsLogin: true }),
         emitSuccessNode: (node) => emitEvent('debug_connection_success', { node }),
         updateClockSkewFromSuccess: (serverUnixSeconds) => connectionManager.updateClockSkewFromSuccess(serverUnixSeconds),
         shouldWarmupMediaConn: () => !!(getCurrentCredentials()?.meJid && connectionManager.isConnected()),
@@ -145,6 +146,7 @@ function createIncomingNodeRuntime(input) {
         emitIncomingFailure: (event) => emitEvent('stream_failure', event),
         emitIncomingErrorStanza: (event) => emitEvent('stanza_error', event),
         emitIncomingNotification: (event) => emitEvent('debug_notification', event),
+        emitOfflineThreadMetadata: (event) => emitEvent('offline_thread_metadata', event),
         emitMexNotification: (event) => emitEvent('mex_notification', event),
         emitRegistrationCode: (event) => emitEvent('mobile_registration_code', event),
         emitAccountTakeoverNotice: (event) => emitEvent('mobile_account_takeover_notice', event),
@@ -240,6 +242,15 @@ export function buildWaClientDependencies(input) {
             allowPrivateHosts: linkPreviewOptions.allowPrivateHosts,
             proxy: linkPreviewOptions.proxy ?? options.proxy?.linkPreview
         });
+    const createLinkPreviewResolver = (surface) => (content) => resolveLinkPreview(content.text, content.linkPreview, {
+        logger,
+        mediaTransfer,
+        getMediaConn: () => getClientMediaConn(mediaMessageBuildOptions),
+        fetcher: linkPreviewFetcher,
+        options: linkPreviewOptions,
+        serverClock,
+        surface
+    });
     const mediaMessageBuildOptions = {
         logger,
         mediaTransfer,
@@ -257,14 +268,7 @@ export function buildWaClientDependencies(input) {
         },
         serverClock,
         media: options.media,
-        linkPreviewResolver: (content) => resolveLinkPreview(content.text, content.linkPreview, {
-            logger,
-            mediaTransfer,
-            getMediaConn: () => getClientMediaConn(mediaMessageBuildOptions),
-            fetcher: linkPreviewFetcher,
-            options: linkPreviewOptions,
-            serverClock
-        })
+        linkPreviewResolver: createLinkPreviewResolver()
     };
     const messageClient = new WaMessageClient({
         logger,
@@ -325,6 +329,7 @@ export function buildWaClientDependencies(input) {
     const authClient = new WaAuthClient({
         deviceBrowser: options.deviceBrowser,
         deviceOsDisplayName: options.deviceOsDisplayName,
+        deviceOsVersion: options.deviceOsVersion,
         devicePlatform: options.devicePlatform,
         requireFullSync: options.requireFullSync,
         version: options.version,
@@ -367,12 +372,16 @@ export function buildWaClientDependencies(input) {
         generateStanzaId: () => messageDispatch.generateOutgoingMessageId(),
         mediaTransfer,
         getMediaConn: () => getClientMediaConn(mediaMessageBuildOptions),
+        linkPreviewResolver: createLinkPreviewResolver('newsletter'),
         getAbPropString: (name) => abPropsCoordinator.getConfigValue(name),
         logger
     });
     const privacyCoordinator = createPrivacyCoordinator({
+        logger,
         queryWithContext: runtime.queryWithContext,
-        resolveUserJidPair: (userJid) => signalDeviceSync.resolveUserJidPair(userJid)
+        resolveUserJidPair: (userJid) => signalDeviceSync.resolveUserJidPair(userJid),
+        getSelfLid: () => getCurrentCredentials()?.meLid ?? null,
+        emitPrivacy: (event) => runtime.emitEvent('privacy', event)
     });
     const businessCoordinator = createBusinessCoordinator({
         queryWithContext: runtime.queryWithContext,
@@ -411,7 +420,8 @@ export function buildWaClientDependencies(input) {
             }
             return {
                 participants: participantJids,
-                ephemeral: metadata.ephemeral
+                ephemeral: metadata.ephemeral,
+                ephemeralTrigger: metadata.ephemeralTrigger
             };
         },
         logger
@@ -466,6 +476,8 @@ export function buildWaClientDependencies(input) {
         sessionStore: sessionStore.session,
         identityStore: sessionStore.identity,
         deviceListStore: sessionStore.deviceList,
+        threadStore: sessionStore.threads,
+        chatMetadataStore: sessionStore.chatMetadata,
         signalDeviceSync,
         messageSecretStore: sessionStore.messageSecret,
         persistAllMessageSecrets: options.addons?.persistAllSecrets === true,
@@ -508,7 +520,9 @@ export function buildWaClientDependencies(input) {
         trustedContactToken,
         emitAddon: (event) => runtime.emitEvent('message_addon', event),
         mexSocket: { query: runtime.query },
-        peerDataOperation
+        peerDataOperation,
+        isGroupHistorySendEnabled: () => abPropsCoordinator.getConfigValue('group_history_send'),
+        getAbPropNumber: (name) => abPropsCoordinator.getConfigValue(name)
     });
     const retryCoordinator = new WaRetryCoordinator({
         logger,
@@ -533,7 +547,8 @@ export function buildWaClientDependencies(input) {
                 .handleIncomingMessageEvent(event)
                 .catch((err) => runtime.handleError(toError(err)));
         },
-        isMobilePrimary
+        isMobilePrimary,
+        getAbPropNumber: (name) => abPropsCoordinator.getConfigValue(name)
     });
     const botCoordinator = createBotCoordinator({
         logger,
@@ -645,6 +660,7 @@ export function buildWaClientDependencies(input) {
     const disconnectWithClientSideEffects = async (reason, isLogout, code) => {
         abPropsCoordinator.reset();
         offlineResume.reset();
+        privacyCoordinator.stopAccountSyncRefresh();
         await connectionManager?.disconnect();
         runtime.emitEvent('connection', {
             status: 'close',
@@ -691,6 +707,7 @@ export function buildWaClientDependencies(input) {
         signalProtocol,
         senderKeyManager,
         onDecryptFailure: (context, error) => retryCoordinator.onDecryptFailure(context, error),
+        requestPlaceholderResend: (context) => retryCoordinator.onUnavailableMessage(context),
         emitIncomingMessage: (event) => {
             void runtime
                 .handleIncomingMessageEvent(event)
@@ -706,6 +723,10 @@ export function buildWaClientDependencies(input) {
         getCurrentCredentials,
         syncAppState: runtime.syncAppState,
         generateUsyncSid,
+        syncAccountPrivacy: async () => {
+            await privacyCoordinator.refreshFromAccountSync();
+        },
+        emitBlocklist: (blocklist) => runtime.emitEvent('blocklist', blocklist),
         newsletterListSubscribed: () => newsletterCoordinator.listSubscribed()
     }, dirtyBits);
     const offlineResume = new WaOfflineResumeCoordinator({
@@ -887,6 +908,25 @@ export function buildWaClientDependencies(input) {
             return false;
         }
     });
+    incomingNode.registerIncomingHandler({
+        tag: WA_NODE_TAGS.NOTIFICATION,
+        subtype: WA_NOTIFICATION_TYPES.ACCOUNT_SYNC,
+        prepend: true,
+        /**
+         * The stanza carries the changed `<category>` inline, but it is a
+         * trigger only: the payload is a partial view, so the whole set is
+         * refetched instead. Observer only - returning false keeps the
+         * generic notification handler responsible for the ack and the
+         * `debug_notification` emit, leaving wire behavior unchanged.
+         */
+        // eslint-disable-next-line @typescript-eslint/require-await
+        handler: async (node) => {
+            if (findNodeChild(node, WA_NODE_TAGS.PRIVACY)) {
+                privacyCoordinator.scheduleAccountSyncRefresh();
+            }
+            return false;
+        }
+    });
     incomingNode.registerIncomingHandler({
         tag: WA_NODE_TAGS.NOTIFICATION,
         subtype: WA_NOTIFICATION_TYPES.DEVICES,

package/dist/esm/client/coordinators/WaAbPropsCoordinator.js

@@ -1,8 +1,13 @@
+import { resolveAbPropNameByCode, WA_ABPROPS } from '../../abprops-spec.js';
 import { parseAbPropsIqResult } from '../events/abprops.js';
-import { AB_PROP_CONFIGS, resolveAbPropNameByCode, WA_ABPROPS_REFRESH_BOUNDS } from '../../protocol/abprops.js';
+import { WA_ABPROPS_REFRESH_BOUNDS } from '../../protocol/abprops.js';
 import { WA_DEFAULTS } from '../../protocol/constants.js';
 import { buildGetAbPropsIq } from '../../transport/node/builders/abprops.js';
-import { parseOptionalInt, toError } from '../../util/primitives.js';
+import { toError } from '../../util/primitives.js';
+// The generated table types every entry with literal `code` / `defaultValue`
+// types. Reading through a widened view keeps a lookup by a non-literal name
+// from expanding into a 2000-member union at every call site.
+const AB_PROPS = WA_ABPROPS;
 export class WaAbPropsCoordinator {
     constructor(options) {
         this.logger = options.logger;
@@ -18,7 +23,7 @@ export class WaAbPropsCoordinator {
         if (cached !== undefined) {
             return cached;
         }
-        return AB_PROP_CONFIGS[name].defaultValue;
+        return AB_PROPS[name].defaultValue;
     }
     sync() {
         if (this.syncPromise) {
@@ -105,7 +110,7 @@ export class WaAbPropsCoordinator {
             if (!name) {
                 continue;
             }
-            const config = AB_PROP_CONFIGS[name];
+            const config = AB_PROPS[name];
             const parsed = parseConfigValue(entry.configValue, config.type, config.defaultValue);
             this.cache.set(name, parsed);
             applied += 1;
@@ -119,6 +124,8 @@ export class WaAbPropsCoordinator {
         });
     }
 }
+// parseInt, not a digits-only parse: negative values are in band, several props
+// ship -1 as their default. Divergence: WA Web caches NaN, we keep the default.
 function parseConfigValue(value, type, defaultValue) {
     if (value === null) {
         return defaultValue;
@@ -127,7 +134,12 @@ function parseConfigValue(value, type, defaultValue) {
         return value === '1' || value === 'true' || value === 'True';
     }
     if (type === 'int') {
-        return parseOptionalInt(value) ?? defaultValue;
+        const parsed = Number.parseInt(value, 10);
+        return Number.isNaN(parsed) ? defaultValue : parsed;
+    }
+    if (type === 'float') {
+        const parsed = Number.parseFloat(value);
+        return Number.isNaN(parsed) ? defaultValue : parsed;
     }
     return value;
 }

package/dist/esm/client/coordinators/WaIncomingNodeCoordinator.js

@@ -1,5 +1,6 @@
 import { parseChatstateNode } from '../events/chatstate.js';
 import { buildInboundAck, createIncomingBaseEvent, createIncomingBusinessNotificationHandler, createIncomingCallHandler, createIncomingFailureHandler, createIncomingGroupNotificationHandler, createIncomingNotificationHandler, createIncomingPictureNotificationHandler, createIncomingReceiptHandler, createIncomingRegistrationNotificationHandler, createInfoBulletinNotificationEvent, createUnhandledIncomingNodeEvent, sendSafeAck } from '../events/incoming.js';
+import { parseOfflineThreadMetadata } from '../events/offline.js';
 import { parsePresenceNode } from '../events/presence.js';
 import { WA_IQ_TYPES, WA_MESSAGE_TAGS, WA_MESSAGE_TYPES, WA_NODE_TAGS, WA_NOTIFICATION_TYPES, WA_SIGNALING } from '../../protocol/constants.js';
 import { decodeNodeContentBase64OrBytes, findNodeChild, getNodeChildren, getNodeChildrenByTag } from '../../transport/node/helpers.js';
@@ -378,6 +379,9 @@ export class WaIncomingNodeCoordinator {
                 if (child.tag === 'offline') {
                     this.offlineResume.handleOfflineComplete(parseOptionalInt(child.attrs.count) ?? 0);
                 }
+                if (child.tag === 'thread_metadata') {
+                    this.runtime.emitOfflineThreadMetadata(parseOfflineThreadMetadata(child));
+                }
                 handled = true;
             }
         }

package/dist/esm/client/coordinators/WaMessageCoordinator.js

@@ -6,12 +6,26 @@ import { uploadMedia } from '../messaging/messages.js';
 import { MEDIA_UPLOAD_PATHS } from '../../media/constants.js';
 import { buildAddonAdditionalData, decodeAddonPlaintext, decryptAddonPayload, identifyEncryptedAddon, resolveParentMessageSecret, resolvePollOptionNames, shouldUseAddonAdditionalData } from '../../message/crypto/addon-crypto.js';
 import { unwrapMessage } from '../../message/encode/content.js';
+import { encodeGroupHistoryBundle } from '../../message/kinds/group-history.js';
 import { proto } from '../../proto.js';
-import { applyDeviceToJid, normalizeRecipientJid } from '../../protocol/jid.js';
+import { applyDeviceToJid, isGroupJid, normalizeRecipientJid } from '../../protocol/jid.js';
 import { runMexQuery } from '../../transport/node/mex/client.js';
 import { readAllBytes } from '../../util/bytes.js';
-import { tryAsNumber, tryAsString } from '../../util/coercion.js';
-import { toError } from '../../util/primitives.js';
+import { resolveOptionalPositive, resolvePositive, tryAsNumber, tryAsString } from '../../util/coercion.js';
+import { longToNumber, toError } from '../../util/primitives.js';
+/** MIME type the group-history bundle is uploaded and advertised under. */
+const GROUP_HISTORY_BUNDLE_MIMETYPE = 'application/protobuf';
+/** Oldest `messageTimestamp` across `messages`, in seconds; `undefined` when none carries one. */
+function oldestTimestampSeconds(messages) {
+    let oldest;
+    for (let index = 0; index < messages.length; index += 1) {
+        const timestamp = longToNumber(messages[index].messageTimestamp);
+        if (timestamp > 0 && (oldest === undefined || timestamp < oldest)) {
+            oldest = timestamp;
+        }
+    }
+    return oldest;
+}
 function parseReachoutTimelockMexResponse(data) {
     const root = data?.xwa2_fetch_account_reachout_timelock;
     return {
@@ -70,6 +84,8 @@ export class WaMessageCoordinator {
         this.emitAddon = deps.emitAddon;
         this.mexSocket = deps.mexSocket;
         this.peerDataOperation = deps.peerDataOperation;
+        this.isGroupHistorySendEnabled = deps.isGroupHistorySendEnabled;
+        this.getAbPropNumber = deps.getAbPropNumber;
     }
     /**
      * Asks the server to backfill older messages for `chatJid` beyond what
@@ -86,13 +102,7 @@ export class WaMessageCoordinator {
      */
     async requestHistorySync(input) {
         const chatJid = normalizeRecipientJid(input.chatJid);
-        if (input.count !== undefined) {
-            if (!Number.isFinite(input.count) ||
-                !Number.isSafeInteger(input.count) ||
-                input.count <= 0) {
-                throw new Error(`invalid count: ${input.count}`);
-            }
-        }
+        const onDemandMsgCount = resolveOptionalPositive(input.count, 'count');
         if (input.oldestMsgTimestampMs !== undefined) {
             if (!Number.isFinite(input.oldestMsgTimestampMs) ||
                 !Number.isSafeInteger(input.oldestMsgTimestampMs) ||
@@ -110,10 +120,155 @@ export class WaMessageCoordinator {
             ...(input.oldestMsgTimestampMs === undefined
                 ? {}
                 : { oldestMsgTimestampMs: input.oldestMsgTimestampMs }),
-            ...(input.count === undefined ? {} : { onDemandMsgCount: input.count })
+            ...(onDemandMsgCount === undefined ? {} : { onDemandMsgCount })
         };
         return this.peerDataOperation.send(proto.Message.PeerDataOperationRequestType.HISTORY_SYNC_ON_DEMAND, { historySyncOnDemandRequest });
     }
+    /**
+     * Shares recent group history with members who joined after the fact - the
+     * counterpart of the `group_history_bundle` event on the receiving side.
+     *
+     * Sends two messages: the bundle itself, encrypted per device and fanned
+     * out **only** to `toJids` (never to the whole group), followed by a hidden
+     * notice addressed to everyone so other clients can render the "history was
+     * shared" marker.
+     *
+     * WhatsApp gates the sender side per account through the `group_history_send`
+     * AB-prop and rejects the stanza with SMAX_INVALID when it is off, so this
+     * throws up front rather than spending an upload. Admin-only groups
+     * (`memberShareGroupHistoryMode: 'admin_share'`) reject a share from a
+     * regular member server-side - read `client.group.queryGroupMetadata()`
+     * first if you want to check that too.
+     *
+     * @throws when the account is not allowed to share group history, when
+     * `groupJid` is not a group, when any of `toJids` is not a current member
+     * (or is this account), or when there is nothing to bundle.
+     * @example
+     * ```ts
+     * await client.message.shareGroupHistory('12036@g.us', {
+     *     toJids: ['5511999999999@s.whatsapp.net'],
+     *     count: 50
+     * })
+     * ```
+     */
+    async shareGroupHistory(groupJid, input) {
+        const normalizedGroupJid = normalizeRecipientJid(groupJid);
+        if (!isGroupJid(normalizedGroupJid)) {
+            throw new Error(`shareGroupHistory requires a group jid: ${normalizedGroupJid}`);
+        }
+        if (input.toJids.length === 0) {
+            throw new Error('shareGroupHistory requires at least one recipient');
+        }
+        const messageLimit = resolvePositive(input.count, this.getAbPropNumber('group_history_message_count_limit'), 'count');
+        if (!this.isGroupHistorySendEnabled()) {
+            throw new Error('shareGroupHistory is disabled for this account (group_history_send is off)');
+        }
+        const audience = await this.messageDispatch.resolveGroupHistoryAudience(normalizedGroupJid, input.toJids);
+        if (audience.requestedSelf) {
+            throw new Error('shareGroupHistory cannot share history with this account itself');
+        }
+        if (audience.unknownJids.length > 0) {
+            throw new Error(`shareGroupHistory recipients are not members of the group (addressing mode: ${audience.addressingMode}): ${audience.unknownJids.join(', ')}`);
+        }
+        if (audience.historyReceivers.length === 0) {
+            throw new Error('shareGroupHistory resolved no recipients');
+        }
+        const messages = input.messages ??
+            (await this.loadGroupHistoryMessages(normalizedGroupJid, messageLimit, input.sinceMs));
+        if (messages.length === 0) {
+            throw new Error('shareGroupHistory found no messages to share');
+        }
+        const { compressed } = await encodeGroupHistoryBundle(messages, input.outOfWindowPinnedMessages);
+        const upload = await uploadMedia(this.mediaUploadOptions, {
+            source: compressed,
+            cryptoType: 'group-history',
+            uploadPath: MEDIA_UPLOAD_PATHS['group-history'],
+            contentType: GROUP_HISTORY_BUNDLE_MIMETYPE,
+            sidecar: false,
+            logLabel: 'group history bundle upload'
+        });
+        const oldestInWindow = oldestTimestampSeconds(messages);
+        const oldestPin = oldestTimestampSeconds(input.outOfWindowPinnedMessages ?? []);
+        const oldestInBundle = oldestPin === undefined
+            ? oldestInWindow
+            : oldestInWindow === undefined
+                ? oldestPin
+                : Math.min(oldestInWindow, oldestPin);
+        const metadata = {
+            historyReceivers: audience.historyReceivers,
+            nonHistoryReceivers: audience.nonHistoryReceivers,
+            messageCount: messages.length,
+            oldestMessageTimestampInWindow: oldestInWindow,
+            oldestMessageTimestampInBundle: oldestInBundle
+        };
+        const bundleResult = await this.send(normalizedGroupJid, {
+            messageHistoryBundle: {
+                mimetype: GROUP_HISTORY_BUNDLE_MIMETYPE,
+                fileSha256: upload.fileSha256,
+                fileEncSha256: upload.fileEncSha256,
+                mediaKey: upload.mediaKey,
+                directPath: upload.directPath,
+                mediaKeyTimestamp: this.mediaUploadOptions.serverClock.nowSeconds(),
+                messageHistoryMetadata: metadata
+            }
+        });
+        let noticeMessageId;
+        try {
+            noticeMessageId = (await this.send(normalizedGroupJid, {
+                messageHistoryNotice: { messageHistoryMetadata: metadata }
+            })).id;
+        }
+        catch (error) {
+            this.logger.warn('group history notice failed after the bundle was delivered', {
+                groupJid: normalizedGroupJid,
+                id: bundleResult.id,
+                receiverCount: audience.historyReceivers.length,
+                message: toError(error).message
+            });
+        }
+        this.logger.debug('shared group history', {
+            groupJid: normalizedGroupJid,
+            id: bundleResult.id,
+            messagesCount: messages.length,
+            receiverCount: audience.historyReceivers.length
+        });
+        return {
+            bundleMessageId: bundleResult.id,
+            noticeMessageId,
+            messagesCount: messages.length,
+            historyReceivers: audience.historyReceivers,
+            nonHistoryReceivers: audience.nonHistoryReceivers
+        };
+    }
+    /**
+     * Reads the most recent messages of a group back out of the mailbox store
+     * and rebuilds the `WebMessageInfo` shape a bundle carries. Yields nothing
+     * when the `messages` store domain is `'none'`.
+     */
+    async loadGroupHistoryMessages(groupJid, limit, sinceMs) {
+        const records = await this.messageStore.listByThread(groupJid, limit);
+        const messages = [];
+        for (let index = 0; index < records.length; index += 1) {
+            const record = records[index];
+            if (!record.messageBytes) {
+                continue;
+            }
+            if (sinceMs !== undefined && (record.timestampMs ?? 0) < sinceMs) {
+                continue;
+            }
+            messages[messages.length] = {
+                key: {
+                    id: record.id,
+                    remoteJid: groupJid,
+                    fromMe: record.fromMe,
+                    participant: record.participantJid ?? record.senderJid
+                },
+                message: proto.Message.decode(record.messageBytes),
+                messageTimestamp: Math.floor((record.timestampMs ?? 0) / 1000)
+            };
+        }
+        return messages;
+    }
     /**
      * Fetches the server-side "reachout" timelock that throttles cold outreach
      * to non-contacts, returning the active window when enforcement is on.