zapo-js 1.6.2 → 1.7.0

package/dist/client/types.d.ts

@@ -2,8 +2,10 @@ import type { AppStateCollectionName } from '../appstate/types';
 import type { DataForKey, WaAppstateActionKey, WaAppstateIndexArgs } from '../appstate-spec';
 import type { WaShortcakeAssertionSigner } from '../auth/pairing/WaShortcakeFlow';
 import type { WaAuthClientOptions, WaAuthCredentials, WaAuthDangerousOptions, WaAuthSocketOptions } from '../auth/types';
+import type { WaPrivacyAccountSyncResult } from './coordinators/WaPrivacyCoordinator';
 import type { WaCallGroupParticipant, WaCallType } from './events/call';
 import type { IncomingPresenceType, PresenceLastSeen } from './events/presence';
+import type { WaBlocklistResult } from './events/privacy';
 import type { CompanionHostPersistence } from './persistence/companion-host';
 import type { WaClientPluginDefinition } from './plugins/types';
 import type { WaMediaProcessor } from '../media/processor';
@@ -148,7 +150,9 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
      * on-demand backfill triggered by `message.requestHistorySync`) are
      * downloaded and emitted as `history_sync_chunk` events. Set
      * `enabled: false` to drop them; `requireFullSync: true` asks the
-     * primary device for a full history download instead of just recent.
+     * primary device for a full history download instead of just recent;
+     * `groupBundles: true` opts into the group-history bundle a member may
+     * share after somebody joins a group.
      */
     readonly history?: WaHistorySyncOptions;
     /**
@@ -315,6 +319,14 @@ export interface WaHistorySyncOptions {
      */
     readonly enabled?: boolean;
     readonly requireFullSync?: boolean;
+    /**
+     * Whether to download and process the group-history bundle a member may
+     * share after somebody joins a group, emitting `group_history_bundle`.
+     * **Off by default** - a bundle is media a third party pushes at this
+     * account unprompted, so fetching it is opt-in. Bundles addressed to
+     * other members are dropped either way.
+     */
+    readonly groupBundles?: boolean;
 }
 export interface WaSignalMessagePublishInput {
     readonly to: string;
@@ -375,9 +387,23 @@ export interface WaSendMessageOptions extends WaMessagePublishOptions {
      */
     readonly expirationSeconds?: number;
     /**
-     * Skip the automatic `ephemeralSettingTimestamp`/`expiration` injection
-     * applied to messages sent into groups with disappearing-mode on (the cached
-     * group ephemeral is otherwise fetched and applied for you). Off by default.
+     * Unix seconds when disappearing-mode was enabled, sent as
+     * `contextInfo.ephemeralSettingTimestamp`. 1:1 only – groups never carry it.
+     * Overrides the value the auto-inject resolves from the thread store; omit
+     * it unless you have a reason, since a missing timestamp makes the peer warn
+     * that the message will not disappear.
+     */
+    readonly ephemeralSettingTimestamp?: number;
+    /**
+     * Overrides `contextInfo.disappearingMode.trigger`. The 1:1 auto-inject
+     * already sets `CHAT_SETTING`.
+     */
+    readonly disappearingModeTrigger?: Proto.DisappearingMode.Trigger;
+    /**
+     * Skip the automatic disappearing-message injection on **group** sends, which
+     * would otherwise stamp `contextInfo.expiration` and `disappearingMode` from
+     * the group metadata cache. Has no effect on 1:1 – see
+     * {@link disableDirectEphemeralAutoInject}. Off by default.
      *
      * Relationship with {@link expirationSeconds}: a non-undefined
      * `expirationSeconds` already short-circuits the auto-inject, so this flag is
@@ -385,6 +411,17 @@ export interface WaSendMessageOptions extends WaMessagePublishOptions {
      * auto-inject AND not set any expiration yourself.
      */
     readonly disableGroupEphemeralAutoInject?: boolean;
+    /**
+     * Skip the automatic disappearing-message injection on **1:1** sends, which
+     * would otherwise stamp `contextInfo.expiration`,
+     * `ephemeralSettingTimestamp` and `disappearingMode` from the chat metadata
+     * cache. Also skips the cache lookup itself. Has no effect on groups – see
+     * {@link disableGroupEphemeralAutoInject}. Off by default.
+     *
+     * Same relationship with {@link expirationSeconds} as the group flag: a
+     * non-undefined `expirationSeconds` already short-circuits the auto-inject.
+     */
+    readonly disableDirectEphemeralAutoInject?: boolean;
     /** Raw child nodes appended to the `<message>` stanza. Escape hatch for protocol features the typed API doesn't cover. */
     readonly customNodes?: readonly BinaryNode[];
     /** Wrap the outgoing message as view-once. Only valid for image/video/audio content. */
@@ -788,19 +825,26 @@ export interface WaIncomingUnhandledStanzaEvent extends WaIncomingBaseEvent {
     readonly reason: string;
 }
 /**
- * Why an incoming message arrived as a content-less placeholder. `view_once`:
- * a view-once already consumed elsewhere. `hosted`: a hosted/bot message that
- * could not be fanned out. `other`: an `unavailable` marker the lib does not
- * categorize yet.
+ * Why an incoming message arrived as a content-less placeholder. `view_once`: a
+ * view-once already consumed elsewhere. `hosted`: a hosted account whose message
+ * could not be fanned out. `bot`: a bot message whose fanout never ran. `other`:
+ * a plain fanout placeholder – the only kind the primary device resends.
  */
-export type WaUnavailableMessageKind = 'view_once' | 'hosted' | 'other';
+export type WaUnavailableMessageKind = 'view_once' | 'hosted' | 'bot' | 'other';
 export interface WaIncomingUnavailableMessageEvent extends Omit<WaIncomingBaseEvent, 'chatJid' | 'stanzaId'> {
     /** Which flavour of content the server signalled as unavailable. */
     readonly kind: WaUnavailableMessageKind;
+    /**
+     * `true` when a resend was queued for the primary device; the payload then
+     * arrives as a `message` event with the same key. Best-effort, like wa-web:
+     * the request is not persisted, so a failed peer message is not retried.
+     * `false` for the unrecoverable flavours, messages past the server age
+     * window, and mobile-primary sessions.
+     */
+    readonly resendRequested: boolean;
     /**
      * The message key (chat, stanza id, author, addressing metadata) – same
-     * shape the `message` event carries, so it can be stored or correlated. There
-     * is no decrypted `message`: the payload is unavailable and cannot be fetched.
+     * shape the `message` event carries, so it can be stored or correlated.
      */
     readonly key: WaIncomingMessageKey;
     /** Stanza `t` attr (seconds since epoch). */
@@ -1032,6 +1076,32 @@ export interface WaHistorySyncChunkEvent {
     /** Server-reported progress, 0–100. */
     readonly progress?: number;
 }
+/**
+ * A group-history bundle shared with this account after it joined a group,
+ * already downloaded, filtered and persisted. Emitted once per bundle, only
+ * when `history.groupBundles` is enabled.
+ */
+export interface WaGroupHistoryBundleEvent {
+    readonly groupJid: string;
+    /** Member who shared the history. */
+    readonly senderJid?: string;
+    /** Stanza id of the message that carried the bundle. */
+    readonly bundleMessageId?: string;
+    /** Messages persisted from this bundle, after filtering. */
+    readonly messagesCount: number;
+    /** Pinned messages older than the shared window, exempt from the age cutoff. */
+    readonly outOfWindowPinsCount: number;
+    /** Entries skipped as stubs, foreign-chat, ephemeral-expired or too old. */
+    readonly droppedCount: number;
+    /** Oldest persisted message timestamp, in ms. */
+    readonly oldestTimestampMs?: number;
+    /**
+     * Members the sender addressed the bundle to (PN or LID form). Copied out
+     * of the decoded payload, so mutating it cannot corrupt the message proto
+     * the `message` event handed to the same listener.
+     */
+    readonly historyReceivers: readonly string[];
+}
 export type WaAppStateMutationSource = 'snapshot' | 'patch' | 'local';
 type MutationEventBase = {
     readonly source: WaAppStateMutationSource;
@@ -1168,11 +1238,11 @@ export interface WaClientEventMap {
      */
     readonly message_protocol: (event: WaIncomingProtocolMessageEvent) => void;
     /**
-     * A message the server delivered as a content-less placeholder: the payload
-     * is unavailable and cannot be recovered (a view-once already consumed, or a
-     * hosted/bot message that could not be fanned out). The lib acks it and emits
-     * this instead of a `message` event for the same stanza. Branch on
-     * `event.kind`.
+     * A message the server delivered as a content-less placeholder. The lib acks
+     * it and emits this instead of a `message` event for the same stanza. A plain
+     * fanout placeholder is asked back from the primary device and arrives later
+     * as a `message` event (see `event.resendRequested`); a consumed view-once or
+     * a hosted/bot message that could not be fanned out is never resent.
      */
     readonly message_unavailable: (event: WaIncomingUnavailableMessageEvent) => void;
     /**
@@ -1205,6 +1275,28 @@ export interface WaClientEventMap {
     readonly business: (event: WaBusinessEvent) => void;
     /** Profile/group/community picture change notification – the new picture must still be fetched explicitly. */
     readonly picture: (event: WaPictureEvent) => void;
+    /**
+     * The account's privacy, refetched after the primary or another companion
+     * changed it: the full category set plus any disallowed list the server
+     * reported. The two halves are read by separate queries, so a change
+     * landing mid-refresh can leave them describing slightly different server
+     * states - the payload is exactly what
+     * {@link WaPrivacyCoordinator.refreshFromAccountSync} returns.
+     *
+     * Two paths trigger it: the live `account_sync` notification (debounced,
+     * so a burst of changes on the phone collapses into one refresh) and the
+     * `account_sync` dirty bit that catches a session up after being offline.
+     * Neither is trusted for its payload - the values always come from a
+     * fresh read. Categories the library does not model are dropped.
+     */
+    readonly privacy: (event: WaPrivacyAccountSyncResult) => void;
+    /**
+     * The account blocklist after a block/unblock made on another device -
+     * same refetch path as `privacy`, from its own account-sync protocol. The
+     * payload is the full list ({@link WaPrivacyCoordinator.getBlocklist}'s
+     * shape), never a delta.
+     */
+    readonly blocklist: (event: WaBlocklistResult) => void;
     /**
      * A parsed app-state mutation arriving from a sync – chat mute/star/read/
      * pin/archive/contact/label/etc. changed on another device. Inbound only;
@@ -1228,12 +1320,24 @@ export interface WaClientEventMap {
      * Skipped only when `history.enabled` is explicitly `false`.
      */
     readonly history_sync_chunk: (event: WaHistorySyncChunkEvent) => void;
+    /**
+     * A group-history bundle another member shared with this account after it
+     * joined a group, already downloaded and persisted. Requires
+     * `history.groupBundles: true` - the download is opt-in because a third
+     * party triggers it.
+     */
+    readonly group_history_bundle: (event: WaGroupHistoryBundleEvent) => void;
     /**
      * Offline-message queue progress after a reconnect (`'resuming'` ticks
      * with `remainingStanzas`, then `'complete'`). Useful to defer UI updates
      * until the catch-up finishes.
      */
     readonly offline_resume: (event: WaOfflineResumeEvent) => void;
+    /**
+     * Preview manifest of the offline queue, sent just before the flush. Not
+     * guaranteed to arrive - use `offline_resume` for progress, never this.
+     */
+    readonly offline_thread_metadata: (event: WaOfflineThreadMetadataEvent) => void;
     /**
      * Fatal stream-level error from the server (e.g. logged out from another
      * device, stream conflict). The connection will close right after.
@@ -1314,6 +1418,36 @@ export interface WaOfflineResumeEvent {
     /** `true` when triggered by an explicit catch-up request rather than auto-resume on reconnect. */
     readonly forced: boolean;
 }
+export interface WaOfflineThreadPreview {
+    /** User (`@lid`/`@s.whatsapp.net`) or group (`@g.us`) jid. */
+    readonly jid: string;
+    /** Unix seconds of the most recent queued stanza for this thread. */
+    readonly timestampSeconds: number;
+}
+export interface WaOfflineThreadReadWatermark {
+    readonly jid: string;
+    /** Unix seconds up to which the peer has already read this thread. */
+    readonly readTimestampSeconds: number;
+}
+/**
+ * Which threads have queued traffic, announced right before the offline flush.
+ * Informational only - every listed thread still delivers its stanzas
+ * normally. All fields but `threads` depend on server gating and are commonly
+ * absent.
+ */
+export interface WaOfflineThreadMetadataEvent {
+    readonly threads: readonly WaOfflineThreadPreview[];
+    readonly readWatermarks?: readonly WaOfflineThreadReadWatermark[];
+    /** Status-update backlog still queued behind this flush. */
+    readonly pendingStatusMessages?: {
+        readonly count: number;
+        readonly jids: readonly string[];
+    };
+    /** Notification backlog still queued behind this flush. */
+    readonly pendingNotifications?: {
+        readonly count: number;
+    };
+}
 export interface WaPrivacyTokenUpdateEvent {
     /** Peer whose trusted-contact-token (TC token) changed. */
     readonly jid: string;

package/dist/crypto/core/xeddsa.js

@@ -9,17 +9,30 @@ const X25519_1 = require("../curves/X25519");
 const edwards_1 = require("../math/edwards");
 const le_1 = require("../math/le");
 const mod_1 = require("../math/mod");
+const nativeBackend_1 = require("../nativeBackend");
 const bytes_1 = require("../../util/bytes");
 const PREFIX_SIGNATURE_RANDOM = new Uint8Array([
     0xfe, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
     0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff
 ]);
+const nativeBinding = (() => {
+    if (process.env.ZAPO_XEDDSA_FORCE_JS)
+        return null;
+    const mod = (0, nativeBackend_1.resolveNativeCryptoBackend)();
+    if (mod && typeof mod.xeddsaSign === 'function' && typeof mod.xeddsaVerify === 'function') {
+        return { xeddsaSign: mod.xeddsaSign, xeddsaVerify: mod.xeddsaVerify };
+    }
+    return null;
+})();
 /**
  * Verifies an XEdDSA signature over `message` against an X25519 (Montgomery)
  * public key, converting to the Edwards form internally. Returns `false`
  * on shape mismatch instead of throwing.
  */
 async function xeddsaVerify(curvePublicKey, message, signature) {
+    if (nativeBinding) {
+        return nativeBinding.xeddsaVerify(curvePublicKey, message, signature);
+    }
     if (signature.length !== 64) {
         return false;
     }
@@ -44,6 +57,9 @@ async function xeddsaVerify(curvePublicKey, message, signature) {
  */
 async function xeddsaSign(privateKey, message) {
     (0, bytes_1.assertByteLength)(privateKey, 32, `invalid curve25519 private key length ${privateKey.length}`);
+    if (nativeBinding) {
+        return (0, bytes_1.toBytesView)(nativeBinding.xeddsaSign(privateKey, message));
+    }
     const clampedPrivateKey = (0, X25519_1.clampCurvePrivateKeyInPlace)(privateKey);
     const privateScalar = (0, le_1.bytesToBigIntLE)(clampedPrivateKey);
     const encodedPublic = (0, edwards_1.encodeExtendedPoint)((0, edwards_1.scalarMultBase)(privateScalar));

package/dist/crypto/curves/X25519.js

@@ -10,7 +10,17 @@ const constants_1 = require("../curves/constants");
 const types_1 = require("../curves/types");
 const constants_2 = require("../math/constants");
 const fe_1 = require("../math/fe");
+const nativeBackend_1 = require("../nativeBackend");
 const bytes_1 = require("../../util/bytes");
+const nativeX25519ScalarMult = (() => {
+    if (process.env.ZAPO_X25519_FORCE_JS)
+        return null;
+    const mod = (0, nativeBackend_1.resolveNativeCryptoBackend)();
+    if (mod && typeof mod.x25519ScalarMult === 'function') {
+        return mod.x25519ScalarMult;
+    }
+    return null;
+})();
 const diffieHellmanWithCallback = node_crypto_1.diffieHellman;
 let diffieHellmanAsync = null;
 let diffieHellmanAsyncProbed = false;
@@ -120,6 +130,9 @@ class X25519 {
     static async scalarMult(privKey, pubKey) {
         (0, bytes_1.assertByteLength)(privKey, 32, 'x25519 private key must be 32 bytes');
         (0, bytes_1.assertByteLength)(pubKey, 32, 'x25519 public key must be 32 bytes');
+        if (nativeX25519ScalarMult) {
+            return (0, bytes_1.toBytesView)(nativeX25519ScalarMult(privKey, pubKey));
+        }
         const opts = {
             privateKey: x25519PrivateKeyObject(privKey),
             publicKey: x25519PublicKeyObject(pubKey)

package/dist/crypto/nativeBackend.d.ts

@@ -0,0 +1,20 @@
+export interface NativeCryptoModule {
+    readonly x25519ScalarMult?: (privateKey: Uint8Array, publicKey: Uint8Array) => Uint8Array;
+    readonly xeddsaSign?: (privateKey: Uint8Array, message: Uint8Array) => Uint8Array;
+    readonly xeddsaVerify?: (publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array) => boolean;
+}
+declare const ABSENCE_TOKENS: {
+    readonly napi: readonly ["'@zapo-js/native'", "binding.js", "Cannot find native binding"];
+    readonly wasm: readonly ["'@zapo-js/native'", "zapo_native_wasm.js"];
+};
+export type NativeBackendKind = keyof typeof ABSENCE_TOKENS;
+/**
+ * Classifies a backend load failure: `true` means the backend is simply not
+ * available on this install (missing optional package, entry file absent,
+ * no prebuilt binary, ESM build without `require`) and the fallback should
+ * stay silent; `false` means the backend is present but broken and the
+ * degradation deserves a process warning.
+ */
+export declare function isBackendAbsence(backend: NativeBackendKind, error: unknown): boolean;
+export declare function resolveNativeCryptoBackend(): NativeCryptoModule | null;
+export {};

package/dist/crypto/nativeBackend.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBackendAbsence = isBackendAbsence;
+exports.resolveNativeCryptoBackend = resolveNativeCryptoBackend;
+/**
+ * Resolves the optional native crypto accelerator backend shared by the
+ * X25519 and XEdDSA paths. Selected via `ZAPO_NATIVE_BACKEND`:
+ *
+ *   - `auto` (default) – try the NAPI addon first, then the WASM build,
+ *                        then no accelerator.
+ *   - `napi`           – only the compiled Rust NAPI addon (`@zapo-js/native`).
+ *   - `wasm`           – only the wasm-bindgen build of the same Rust core.
+ *                        The shipped artifact targets the web (ESM glue +
+ *                        explicit init) so one build serves browsers and
+ *                        Node; loading it here relies on `require(esm)`,
+ *                        available unflagged on Node 20.19+ / 22.12+.
+ *   - `js` / `none`    – no accelerator; callers fall back to the pure-JS
+ *                        (and `node:crypto`) implementations.
+ *
+ * The module is resolved once and memoised. A failed backend resolves to
+ * `null` (or, under `auto`, falls through to the next one) so callers
+ * transparently fall back to JS. An absent backend stays silent - that is
+ * the expected shape of an optional accelerator - but a present-yet-broken
+ * one (corrupt binary, ABI mismatch, unsupported runtime) emits a process
+ * warning with code `ZAPO_NATIVE_LOAD_FAILED` so the degradation is
+ * visible. The per-primitive `ZAPO_X25519_FORCE_JS` / `ZAPO_XEDDSA_FORCE_JS`
+ * escape hatches are honoured by the callers, not here.
+ */
+const node_fs_1 = require("node:fs");
+const primitives_1 = require("../util/primitives");
+const WASM_MODULE_SPECIFIER = '@zapo-js/native/wasm/pkg/zapo_native_wasm.js';
+const WASM_BINARY_SPECIFIER = '@zapo-js/native/wasm/pkg/zapo_native_wasm_bg.wasm';
+function loadWasmBackend() {
+    const mod = require(WASM_MODULE_SPECIFIER);
+    const wasmBytes = (0, node_fs_1.readFileSync)(require.resolve(WASM_BINARY_SPECIFIER));
+    mod.initSync({ module: wasmBytes });
+    return mod;
+}
+let cached;
+const ABSENCE_TOKENS = {
+    napi: ["'@zapo-js/native'", 'binding.js', 'Cannot find native binding'],
+    wasm: ["'@zapo-js/native'", 'zapo_native_wasm.js']
+};
+/**
+ * Classifies a backend load failure: `true` means the backend is simply not
+ * available on this install (missing optional package, entry file absent,
+ * no prebuilt binary, ESM build without `require`) and the fallback should
+ * stay silent; `false` means the backend is present but broken and the
+ * degradation deserves a process warning.
+ */
+function isBackendAbsence(backend, error) {
+    if (error instanceof ReferenceError) {
+        return error.message.includes('require is not defined');
+    }
+    const { code, message } = (error ?? {});
+    if (typeof message !== 'string')
+        return false;
+    const notFound = code === 'MODULE_NOT_FOUND' || code === 'ERR_MODULE_NOT_FOUND';
+    if (!notFound && !message.includes('Cannot find native binding'))
+        return false;
+    return ABSENCE_TOKENS[backend].some((token) => message.includes(token));
+}
+function warnLoadFailure(backend, error) {
+    process.emitWarning('failed to load native crypto accelerator, falling back', {
+        code: 'ZAPO_NATIVE_LOAD_FAILED',
+        detail: `${backend}: ${(0, primitives_1.toError)(error).message}`
+    });
+}
+function resolveNativeCryptoBackend() {
+    if (cached !== undefined)
+        return cached;
+    const backend = (process.env.ZAPO_NATIVE_BACKEND ?? 'auto').toLowerCase();
+    cached = null;
+    if (backend === 'js' || backend === 'none')
+        return cached;
+    if (backend === 'napi' || backend === 'auto') {
+        try {
+            cached = require('@zapo-js/native');
+        }
+        catch (error) {
+            if (!isBackendAbsence('napi', error))
+                warnLoadFailure('napi', error);
+        }
+    }
+    if (cached === null && (backend === 'wasm' || backend === 'auto')) {
+        try {
+            cached = loadWasmBackend();
+        }
+        catch (error) {
+            if (!isBackendAbsence('wasm', error))
+                warnLoadFailure('wasm', error);
+        }
+    }
+    return cached;
+}

package/dist/esm/abprops-spec.js

@@ -0,0 +1,15 @@
+import { WA_ABPROPS_BY_CODE } from '../../spec/abprops/index.js';
+export { WA_ABPROPS, WA_ABPROPS_BY_CODE, WA_ABPROPS_SPECIAL_EARLY, WA_ABPROPS_USED_BEFORE_INIT, WA_GROUP_ABPROPS, WA_GROUP_ABPROPS_BY_CODE } from '../../spec/abprops/index.js';
+// The reverse map is emitted with numeric literal keys, so it cannot be indexed
+// with a plain `number`. Widening it keeps the lookup a single property read and
+// avoids allocating a parallel Map with 2000+ entries at module init.
+const AB_PROP_NAME_BY_CODE = WA_ABPROPS_BY_CODE;
+/**
+ * Resolves the client-side prop name for a wire config code.
+ *
+ * Returns `undefined` for codes this build does not know about - the server
+ * advertises props from newer bundles, and WA Web drops those rows too.
+ */
+export function resolveAbPropNameByCode(configCode) {
+    return AB_PROP_NAME_BY_CODE[configCode];
+}

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) {