@oxidezap/baileyrs 0.1.3 → 0.2.0

package/lib/Bridge/schema.js

@@ -24,14 +24,17 @@
  */
 import { processHistoryMessage } from '../Utils/process-history-message.js';
 import { isJidGroup } from '../WABinary/jid-utils.js';
-import { asBoolOr, asJidAddressString, asJidString, asNumber, asString, isObject, normalizeDiscriminator, toUnixSeconds } from './primitives.js';
+import { absoluteFromDuration, asBool, asBoolOr, asStringArray, asDurationSeconds, asInt64, asJidAddressString, asJidString, asNumber, asString, asUnixSeconds, isObject, normalizeDiscriminator, toUnixSeconds } from './primitives.js';
 /**
  * Bridge sync-action events (`pin_update`, `mute_update`, etc.) carry the
  * proto action under `data.action`, but the bridge `.d.ts` types it as
  * the unexported `PinAction` / `MuteAction` (resolves to `any`). Narrow
  * once at the call site.
  */
-const extractAction = (data) => isObject(data.action) ? data.action : undefined;
+// Tolerates a missing `data` slot: the adapter table has to be total against
+// whatever the runtime sends, and an entry that reads the action before any
+// other guard would otherwise throw rather than drop (`bridge:adapt-total`).
+const extractAction = (data) => isObject(data?.action) ? data.action : undefined;
 /** A group JID is authoritative when an older producer leaves `is_group` false. */
 const resolveIsGroup = (wireValue, chatJid) => asBoolOr(wireValue, false) || isJidGroup(chatJid) === true;
 const resolveParticipantAlt = (senderAlt, isGroup) => isGroup ? senderAlt : undefined;
@@ -60,7 +63,12 @@ const ADAPTERS = {
     temporary_ban: data => ({
         type: 'temporaryBan',
         code: asNumber(data?.code),
-        expire: asNumber(data?.expire)
+        // The wire sends how long the ban lasts, and WA Web renders it that way
+        // ("you'll be able to use WhatsApp again in {duration}"). The canonical
+        // event promises the instant it lifts, which is what the socket formats
+        // and what a reconnect delay subtracts `Date.now()` from — so the
+        // conversion happens here, once, rather than in each of them.
+        expire: absoluteFromDuration(asDurationSeconds(data?.expire))
     }),
     qr_scanned_without_multidevice: () => ({ type: 'qrScannedWithoutMultidevice' }),
     logged_out: data => ({
@@ -68,51 +76,51 @@ const ADAPTERS = {
         onConnect: asBoolOr(data?.on_connect, false),
         reason: asString(data?.reason)
     }),
-    qr: data => (data.code ? { type: 'qr', code: data.code } : null),
-    pairing_code: data => (data.code ? { type: 'qr', code: data.code } : null),
+    qr: data => (data?.code ? { type: 'qr', code: data?.code } : null),
+    pairing_code: data => (data?.code ? { type: 'qr', code: data?.code } : null),
     pairing_code_refresh: data => ({
         type: 'noop',
         bridgeType: 'pairing_code_refresh',
-        detail: data.force_manual ? 'force_manual' : 'automatic'
+        detail: data?.force_manual ? 'force_manual' : 'automatic'
     }),
     pair_passkey_request: () => ({ type: 'noop', bridgeType: 'pair_passkey_request' }),
     pair_passkey_confirmation: data => ({
         type: 'noop',
         bridgeType: 'pair_passkey_confirmation',
-        detail: data.skip_handoff_ux ? 'handoff_verified' : 'confirmation_required'
+        detail: data?.skip_handoff_ux ? 'handoff_verified' : 'confirmation_required'
     }),
     pair_passkey_error: data => ({
         type: 'noop',
         bridgeType: 'pair_passkey_error',
-        detail: asString(data.error)
+        detail: asString(data?.error)
     }),
     pair_success: data => {
         // `id` and `lid` come typed as `Jid` in the bridge .d.ts, but the
         // bridge actually serializes pair_success.{id,lid} as strings (see
         // the wire log) — accept both shapes.
-        const id = typeof data.id === 'string' ? data.id : asJidString(data.id);
+        const id = typeof data?.id === 'string' ? data?.id : asJidString(data?.id);
         if (!id)
             return null;
         return {
             type: 'pairSuccess',
             id,
-            lid: typeof data.lid === 'string' ? data.lid : asJidString(data.lid),
-            platform: asString(data.platform),
-            businessName: asString(data.business_name)
+            lid: typeof data?.lid === 'string' ? data?.lid : asJidString(data?.lid),
+            platform: asString(data?.platform),
+            businessName: asString(data?.business_name)
         };
     },
     pair_error: data => ({
         type: 'pairError',
-        error: asString(data.error) ?? 'Unknown pairing error',
-        id: typeof data.id === 'string' ? data.id : asJidString(data.id),
-        lid: typeof data.lid === 'string' ? data.lid : asJidString(data.lid),
-        businessName: asString(data.business_name),
-        platform: asString(data.platform)
+        error: asString(data?.error) ?? 'Unknown pairing error',
+        id: typeof data?.id === 'string' ? data?.id : asJidString(data?.id),
+        lid: typeof data?.lid === 'string' ? data?.lid : asJidString(data?.lid),
+        businessName: asString(data?.business_name),
+        platform: asString(data?.platform)
     }),
     connect_failure: data => isObject(data)
-        ? { type: 'connectFailure', message: asString(data.message), reason: asNumber(data.reason) }
+        ? { type: 'connectFailure', message: asString(data?.message), reason: asNumber(data?.reason) }
         : { type: 'connectFailure' },
-    stream_error: data => ({ type: 'streamError', code: asString(data.code) ?? 'unknown' }),
+    stream_error: data => ({ type: 'streamError', code: asString(data?.code) ?? 'unknown' }),
     // ── Messages ──
     message: (data, logger) => adaptMessage(data, logger),
     receipt: (data, logger) => adaptReceipt(data, logger),
@@ -121,16 +129,16 @@ const ADAPTERS = {
     // while NACKs become `messages.update` with status ERROR. Preserve every
     // typed field here so the dispatcher can reproduce both surfaces.
     server_ack: data => {
-        const id = asString(data.id);
+        const id = asString(data?.id);
         if (!id)
             return null;
         return {
             type: 'serverAck',
             id,
-            class: asString(data.class),
-            from: asJidString(data.from),
-            timestamp: asNumber(data.timestamp),
-            error: asString(data.error)
+            class: asString(data?.class),
+            from: asJidString(data?.from),
+            timestamp: asUnixSeconds(data?.timestamp),
+            error: asString(data?.error)
         };
     },
     undecryptable_message: data => {
@@ -141,7 +149,7 @@ const ADAPTERS = {
         // `messages-recv.ts:1352`.
         if (!isObject(data))
             return null;
-        const info = isObject(data.info) ? data.info : undefined;
+        const info = isObject(data?.info) ? data?.info : undefined;
         if (!info)
             return null;
         const src = isObject(info.source) ? info.source : undefined;
@@ -164,45 +172,45 @@ const ADAPTERS = {
             pushName: asString(info.push_name),
             participantAlt: resolveParticipantAlt(senderAlt, isGroup),
             remoteJidAlt: resolveRemoteJidAlt(senderAlt, recipientAlt, isGroup, isFromMe),
-            isUnavailable: asBoolOr(data.is_unavailable, false),
-            unavailableType: asString(data.unavailable_type),
-            decryptFailMode: asString(data.decrypt_fail_mode),
+            isUnavailable: asBoolOr(data?.is_unavailable, false),
+            unavailableType: asString(data?.unavailable_type),
+            decryptFailMode: asString(data?.decrypt_fail_mode),
             raw: data
         };
     },
     // ── Contacts ──
     push_name_update: data => {
-        const jid = asJidString(data.jid);
-        return jid ? { type: 'pushNameUpdate', jid, newPushName: asString(data.new_push_name) } : null;
+        const jid = asJidString(data?.jid);
+        return jid ? { type: 'pushNameUpdate', jid, newPushName: asString(data?.new_push_name) } : null;
     },
     contact_update: data => adaptContactUpdate(data),
     contact_updated: data => adaptContactUpdate(data),
     picture_update: data => {
-        const jid = asJidString(data.jid);
+        const jid = asJidString(data?.jid);
         if (!jid)
             return null;
         return {
             type: 'pictureUpdate',
             jid,
-            removed: asBoolOr(data.removed, false),
-            author: asJidString(data.author),
-            pictureId: asString(data.picture_id)
+            removed: asBoolOr(data?.removed, false),
+            author: asJidString(data?.author),
+            pictureId: asString(data?.picture_id)
         };
     },
     // ── Presence ──
     presence: data => {
-        const from = asJidString(data.from);
+        const from = asJidString(data?.from);
         if (!from)
             return null;
         return {
             type: 'presence',
             from,
-            unavailable: asBoolOr(data.unavailable, false),
-            lastSeen: asNumber(data.last_seen)
+            unavailable: asBoolOr(data?.unavailable, false),
+            lastSeen: asUnixSeconds(data?.last_seen)
         };
     },
     chat_presence: data => {
-        const src = isObject(data.source) ? data.source : undefined;
+        const src = isObject(data?.source) ? data?.source : undefined;
         if (!src)
             return null;
         const chat = asJidString(src.chat);
@@ -211,11 +219,11 @@ const ADAPTERS = {
             return null;
         // Bridge sends `media: ''` for "no media" — normalize to undefined
         // so consumers can rely on field omission as the absence signal.
-        const media = asString(data.media);
+        const media = asString(data?.media);
         // Bridge `state` MUST be one of the two canonical values; defaulting
         // to 'composing' on an unknown/missing value would synthesize a
         // false typing indicator. Drop the event instead.
-        const rawState = asString(data.state);
+        const rawState = asString(data?.state);
         if (rawState !== 'composing' && rawState !== 'paused')
             return null;
         return {
@@ -230,44 +238,44 @@ const ADAPTERS = {
     group_update: (data, logger) => adaptGroupUpdate(data, logger),
     // ── Chat state ──
     archive_update: data => {
-        const jid = asJidString(data.jid);
+        const jid = asJidString(data?.jid);
         if (!jid)
             return null;
         return { type: 'archiveUpdate', jid, archived: asBoolOr(extractAction(data)?.archived, true) };
     },
     pin_update: data => {
-        const jid = asJidString(data.jid);
+        const jid = asJidString(data?.jid);
         if (!jid)
             return null;
         return {
             type: 'pinUpdate',
             jid,
-            timestamp: asNumber(data.timestamp),
+            timestamp: asUnixSeconds(data?.timestamp),
             pinned: asBoolOr(extractAction(data)?.pinned, true)
         };
     },
     mute_update: data => {
-        const jid = asJidString(data.jid);
+        const jid = asJidString(data?.jid);
         if (!jid)
             return null;
         const action = extractAction(data);
         return {
             type: 'muteUpdate',
             jid,
-            timestamp: asNumber(data.timestamp),
+            timestamp: asUnixSeconds(data?.timestamp),
             muted: asBoolOr(action?.muted, true),
-            muteEndTimestamp: asNumber(action?.muteEndTimestamp) ?? asNumber(action?.mute_end_timestamp)
+            muteEndTimestamp: asInt64(action?.muteEndTimestamp) ?? asInt64(action?.mute_end_timestamp)
         };
     },
     star_update: data => adaptStarUpdate(data),
     mark_chat_as_read_update: data => {
-        const jid = asJidString(data.jid);
+        const jid = asJidString(data?.jid);
         if (!jid)
             return null;
         return { type: 'markChatAsReadUpdate', jid, read: asBoolOr(extractAction(data)?.read, true) };
     },
     label_edit_update: data => {
-        const labelId = asString(data.label_id);
+        const labelId = asString(data?.label_id);
         if (!labelId)
             return { type: 'noop', bridgeType: 'label_edit_update' };
         const action = extractAction(data);
@@ -284,39 +292,128 @@ const ADAPTERS = {
         };
     },
     label_association_update: data => {
-        const labelId = asString(data.label_id);
-        const chatJid = asJidString(data.chat_jid);
+        const labelId = asString(data?.label_id);
+        const chatJid = asJidString(data?.chat_jid);
         if (!labelId || !chatJid)
             return { type: 'noop', bridgeType: 'label_association_update' };
         // `action.labeled === true` → label added to the chat, else removed.
         return { type: 'labelAssociation', labelId, chatJid, labeled: asBoolOr(extractAction(data)?.labeled, true) };
     },
+    /**
+     * The per-message half of `labels.association`, which used to have no path.
+     * Same canonical event as the chat one, told apart by carrying a message.
+     */
+    message_label_association_update: data => {
+        const labelId = asString(data?.label_id);
+        const chatJid = asJidString(data?.chat_jid);
+        const messageId = asString(data?.message_id);
+        if (!labelId || !chatJid || !messageId) {
+            return { type: 'noop', bridgeType: 'message_label_association_update' };
+        }
+        return {
+            type: 'labelAssociation',
+            labelId,
+            chatJid,
+            messageId,
+            labeled: asBoolOr(extractAction(data)?.labeled, true)
+        };
+    },
+    /**
+     * What a degraded app-state sync left behind. The engine announces the
+     * connection anyway, so without this a consumer is told a session with no
+     * push name is healthy and has nothing to read that says otherwise.
+     */
+    app_state_sync_failed: data => ({
+        type: 'appStateSyncFailed',
+        fatal: asStringArray(data?.fatal),
+        retryable: asStringArray(data?.retryable),
+        skipped: asStringArray(data?.skipped),
+        connected: asBoolOr(data?.connected, false)
+    }),
+    /**
+     * The QR refs ran out. Upstream ends the socket with `timedOut` when its own
+     * QR timer gives up (`Socket/socket.ts`), which is the same end state, so
+     * this becomes the same terminal close rather than a new signal to learn.
+     */
+    pairing_qr_codes_exhausted: () => ({ type: 'qrCodesExhausted' }),
+    /**
+     * Another linked device turned link previews on or off account-wide.
+     *
+     * Upstream carries this on `settings.update`, reached through app state
+     * (`Utils/chat-utils.ts` branches on `privacySettingDisableLinkPreviewsAction`
+     * and emits the action as the value). Same event, different pipe — so the
+     * value is the action itself, not the decoded flag.
+     *
+     * `previews_disabled` is that flag already decoded by the bridge, which is
+     * what fills the action in when the payload carried the flag alone. The
+     * bridge only emits this event when the wire carried the flag, so the last
+     * fallback is unreachable in practice and exists so the value always has
+     * the field upstream's consumers read.
+     */
+    disable_link_previews_update: data => {
+        const action = extractAction(data);
+        return {
+            type: 'settingUpdate',
+            setting: 'disableLinkPreviews',
+            value: {
+                ...action,
+                isPreviewsDisabled: asBool(action?.isPreviewsDisabled) ?? asBoolOr(data?.previews_disabled, false)
+            }
+        };
+    },
+    /**
+     * A pair-code request failed, so any code the user was shown is spent.
+     *
+     * Same lifecycle as `pair_error`, which is why it adapts to the same
+     * canonical event: the socket lives on and the engine takes another
+     * request, so this must not read as a close, and the code on screen has to
+     * stop being offered. `pairError` is the handler that does both — a
+     * pairing code surfaces as `qr` (see `pairing_code` above), and `connecting`
+     * clears it while saying a fresh one can be asked for.
+     *
+     * `rejection` and `backoff` ride along for the log. Neither changes what a
+     * consumer does here, and the engine owns the retry — but a throttle the
+     * server named itself is the difference between a code that will come back
+     * and one that will not, and dropping it leaves that unexplained.
+     */
+    pairing_code_error: data => ({
+        type: 'pairError',
+        error: asString(data?.error) ?? 'pairing code rejected',
+        rejection: asNumber(data?.rejection),
+        backoff: asNumber(data?.backoff)
+    }),
+    // Acknowledged with no Baileys equivalent: upstream has no channel for a
+    // contact deletion (`contacts.update` only upserts), for quick replies, or
+    // for a call placed on the phone.
+    contact_removed: () => ({ type: 'noop', bridgeType: 'contact_removed' }),
+    quick_reply_update: () => ({ type: 'noop', bridgeType: 'quick_reply_update' }),
+    call_log_sync: () => ({ type: 'noop', bridgeType: 'call_log_sync' }),
     // ── Calls ──
     incoming_call: (data, logger) => adaptIncomingCall(data, logger),
     missed_call: data => {
-        const from = asJidString(data.from);
-        const callId = asString(data.call_id);
+        const from = asJidString(data?.from);
+        const callId = asString(data?.call_id);
         if (!from || !callId)
             return null;
         return {
             type: 'incomingCall',
             from,
-            timestamp: toUnixSeconds(data.timestamp),
-            offline: data.reason === 'offline',
+            timestamp: toUnixSeconds(data?.timestamp),
+            offline: data?.reason === 'offline',
             action: { type: 'timeout', callId }
         };
     },
     call_ended_elsewhere: data => {
-        const from = asJidString(data.from);
-        const callId = asString(data.call_id);
+        const from = asJidString(data?.from);
+        const callId = asString(data?.call_id);
         if (!from || !callId)
             return null;
         return {
             type: 'incomingCall',
             from,
-            timestamp: toUnixSeconds(data.timestamp),
+            timestamp: toUnixSeconds(data?.timestamp),
             offline: false,
-            action: { type: data.outcome === 'accepted' ? 'accept' : 'reject', callId }
+            action: { type: data?.outcome === 'accepted' ? 'accept' : 'reject', callId }
         };
     },
     // ── History sync — fully decoded by the bridge, normalized 1:1 with upstream ──
@@ -361,35 +458,35 @@ const ADAPTERS = {
     self_push_name_updated: () => ({ type: 'noop', bridgeType: 'self_push_name_updated' }),
     offline_sync_completed: data => ({
         type: 'offlineSyncCompleted',
-        count: asNumber(data.count) ?? 0
+        count: asNumber(data?.count) ?? 0
     }),
     offline_sync_preview: () => ({ type: 'noop', bridgeType: 'offline_sync_preview' }),
     dirty_state: data => {
-        const dirtyType = asString(data.dirty_type);
+        const dirtyType = asString(data?.dirty_type);
         if (!dirtyType)
             return null;
-        return { type: 'dirtyState', dirtyType, timestamp: asNumber(data.timestamp) };
+        return { type: 'dirtyState', dirtyType, timestamp: asNumber(data?.timestamp) };
     },
     device_list_update: () => ({ type: 'noop', bridgeType: 'device_list_update' }),
     identity_change: () => ({ type: 'noop', bridgeType: 'identity_change' }),
     disappearing_mode_changed: data => {
-        const jid = asJidString(data.from);
-        const duration = asNumber(data.duration);
+        const jid = asJidString(data?.from);
+        const duration = asNumber(data?.duration);
         if (!jid || duration == null)
             return { type: 'noop', bridgeType: 'disappearing_mode_changed' };
         return {
             type: 'disappearingModeChanged',
             jid,
             duration,
-            settingTimestamp: asNumber(data.setting_timestamp)
+            settingTimestamp: asNumber(data?.setting_timestamp)
         };
     },
     business_status_update: () => ({ type: 'noop', bridgeType: 'business_status_update' }),
     newsletter_live_update: data => {
-        const newsletterJid = asJidString(data.newsletter_jid);
+        const newsletterJid = asJidString(data?.newsletter_jid);
         if (!newsletterJid)
             return { type: 'noop', bridgeType: 'newsletter_live_update' };
-        const rawMessages = Array.isArray(data.messages) ? data.messages : [];
+        const rawMessages = Array.isArray(data?.messages) ? data?.messages : [];
         const messages = rawMessages
             .map(m => {
             if (!isObject(m))
@@ -422,10 +519,10 @@ const ADAPTERS = {
         // (old_lid, old_jid) and (new_lid, new_jid). We learn whatever's
         // present and let the dispatcher fan out one upstream event per
         // pair. Mirrors upstream `messages-recv.ts:287`.
-        const oldJid = asJidString(data.old_jid);
-        const newJid = asJidString(data.new_jid);
-        const oldLid = asJidString(data.old_lid);
-        const newLid = asJidString(data.new_lid);
+        const oldJid = asJidString(data?.old_jid);
+        const newJid = asJidString(data?.new_jid);
+        const oldLid = asJidString(data?.old_lid);
+        const newLid = asJidString(data?.new_lid);
         const mappings = [];
         if (oldLid && oldJid)
             mappings.push({ lid: oldLid, pn: oldJid });
@@ -438,30 +535,30 @@ const ADAPTERS = {
     contact_sync_requested: () => ({ type: 'noop', bridgeType: 'contact_sync_requested' }),
     user_about_update: () => ({ type: 'noop', bridgeType: 'user_about_update' }),
     delete_chat_update: data => {
-        const jid = asJidString(data.jid);
+        const jid = asJidString(data?.jid);
         return jid ? { type: 'chatDelete', jid } : { type: 'noop', bridgeType: 'delete_chat_update' };
     },
     clear_chat_update: data => {
         // Clear = drop all messages but keep the chat. Maps to upstream
         // `messages.delete` `{ jid, all: true }` (the chat-clear surface noted in
         // the messageDelete dispatcher), distinct from chatDelete (whole chat gone).
-        const jid = asJidString(data.jid);
+        const jid = asJidString(data?.jid);
         return jid ? { type: 'chatClear', jid } : { type: 'noop', bridgeType: 'clear_chat_update' };
     },
     // Muting a contact's status (stories) updates. Forwarded for surface completeness,
     // but noop'd: upstream Baileys has no status-mute event/chatModify to map it onto.
     user_status_mute_update: () => ({ type: 'noop', bridgeType: 'user_status_mute_update' }),
     delete_message_for_me_update: data => {
-        const chatJid = asJidString(data.chat_jid);
-        const messageId = asString(data.message_id);
+        const chatJid = asJidString(data?.chat_jid);
+        const messageId = asString(data?.message_id);
         if (!chatJid || !messageId)
             return { type: 'noop', bridgeType: 'delete_message_for_me_update' };
         return {
             type: 'messageDelete',
             chatJid,
             messageId,
-            fromMe: asBoolOr(data.from_me, false),
-            participantJid: asJidString(data.participant_jid)
+            fromMe: asBoolOr(data?.from_me, false),
+            participantJid: asJidString(data?.participant_jid)
         };
     },
     // ── Generic notification / raw node ──
@@ -474,8 +571,8 @@ const ADAPTERS = {
         // CanonicalNotification.attrs (typed `Record<string, string>`).
         // Drop non-string values, coerce the rest.
         const attrs = {};
-        if (isObject(data.attrs)) {
-            for (const [k, v] of Object.entries(data.attrs)) {
+        if (isObject(data?.attrs)) {
+            for (const [k, v] of Object.entries(data?.attrs)) {
                 if (typeof v === 'string')
                     attrs[k] = v;
                 else if (typeof v === 'number' || typeof v === 'boolean')
@@ -484,26 +581,26 @@ const ADAPTERS = {
                 // sense on a flat attrs map anyway.
             }
         }
-        return { type: 'notification', tag: asString(data.tag) ?? 'notification', attrs };
+        return { type: 'notification', tag: asString(data?.tag) ?? 'notification', attrs };
     },
     raw_node: data => {
         // `BinaryNode` is shaped exactly like the bridge payload
         // (`{ tag, attrs, content }`). Minimal sanity check on `tag`.
-        if (!isObject(data) || typeof data.tag !== 'string')
+        if (!isObject(data) || typeof data?.tag !== 'string')
             return null;
         return { type: 'rawNode', node: data };
     },
     mex_notification: data => {
-        const opName = asString(data.op_name);
+        const opName = asString(data?.op_name);
         if (!opName)
             return null;
-        const payload = isObject(data.payload) ? data.payload : {};
+        const payload = isObject(data?.payload) ? data?.payload : {};
         return {
             type: 'mexNotification',
             opName,
-            from: asJidString(data.from),
-            stanzaId: asString(data.stanza_id),
-            offline: asBoolOr(data.offline, false),
+            from: asJidString(data?.from),
+            stanzaId: asString(data?.stanza_id),
+            offline: asBoolOr(data?.offline, false),
             payload
         };
     }
@@ -516,11 +613,35 @@ export const KNOWN_BRIDGE_EVENT_TYPES = new Set(Object.keys(ADAPTERS));
  */
 export const adaptBridgeEventViaSchema = (event, logger) => {
     const typed = event;
-    const adapter = ADAPTERS[typed.type];
-    if (!adapter) {
+    // An own property of the table, not anything the prototype chain answers.
+    //
+    // The type string comes from the runtime, which gets it from the server, so it
+    // is untrusted input into a plain-object lookup. `ADAPTERS.constructor` and
+    // `ADAPTERS.toString` resolve to inherited functions: they were called and
+    // their return values handed on as canonical events — measured, `constructor`
+    // produced an object and `toString` a string, neither of which is an event.
+    // `__proto__` and `valueOf` reached the other failure mode and threw.
+    if (!Object.hasOwn(ADAPTERS, typed.type)) {
         logger?.debug({ eventType: typed.type }, 'unknown bridge event (no canonical mapping)');
         return null;
     }
+    const adapter = ADAPTERS[typed.type];
+    // The slot is passed through exactly as it arrived, nullish included.
+    //
+    // The contract these adapters are documented under is "null on unrecoverable
+    // shape mismatch, never a throw", and a throw here does not stay local: it
+    // propagates into the socket's event dispatch and takes down the whole event
+    // loop rather than the one event. 30 of the 58 declared types threw on an
+    // event that arrived with no data — `data.code` on `undefined` — so every
+    // adapter in the table now reads its slot optionally.
+    //
+    // Substituting an empty object here instead was tried and reverted: `{}` is a
+    // perfectly good object, so it walks straight past the `isObject(data)` guard
+    // that several adapters use to decide the payload is unrecoverable.
+    // `history_sync` then built an empty final batch and the socket emitted a
+    // spurious `messaging-history.set` where it had previously dropped the event.
+    // Each adapter owns that decision; the dispatch must not pre-empt it.
+    //
     // `data` cast here is the only `as` in the public path — the bridge
     // runtime is the source of truth that the type matches the discriminator.
     return adapter(typed.data, logger);

package/lib/Bridge/types.d.ts

@@ -37,6 +37,17 @@ export interface CanonicalPairSuccess {
 export interface CanonicalPairError {
     type: 'pairError';
     error: string;
+    /**
+     * The server's own refusal code, when it answered with one.
+     *
+     * Absent when the failure was local (validation, no connection) or the
+     * request went unanswered — nothing was refused, so there is no status.
+     * Carried for the log only: the consumer-visible outcome is the same
+     * either way, and the engine owns the retry.
+     */
+    rejection?: number;
+    /** Seconds the server asked the client to wait before asking again. */
+    backoff?: number;
     /** Account JID after pairing (may be set even on error). */
     id?: string;
     /** LID for the account. */
@@ -445,9 +456,57 @@ export interface CanonicalLabelAssociation {
     type: 'labelAssociation';
     labelId: string;
     chatJid: string;
-    /** `true` = label added to the chat, `false` = removed. */
+    /**
+     * The message the label is on, for a per-message association.
+     *
+     * Absent means the label is on the chat itself. The two arrive on separate
+     * bridge events and upstream carries both on `labels.association`, keyed by
+     * the association's own `type`.
+     */
+    messageId?: string;
+    /** `true` = label added, `false` = removed. */
     labeled: boolean;
 }
+/**
+ * The server ran out of QR refs before anyone scanned one.
+ *
+ * Terminal: nothing else is coming on this socket, and the consumer builds a
+ * new one to be shown a fresh code.
+ */
+export interface CanonicalQrCodesExhausted {
+    type: 'qrCodesExhausted';
+}
+/**
+ * A batched app-state sync that did not leave every collection synced.
+ *
+ * Collections are named as they appear on the wire. `fatal` is the one a
+ * consumer usually has to act on: the server refused it and asking again gets
+ * the same answer. `connected` says whether the session was announced anyway,
+ * which is the difference between "degraded but usable" and "still retrying" —
+ * the engine connects on a degraded sync rather than withholding the session,
+ * so this event is the only thing that says what is missing from it.
+ */
+export interface CanonicalAppStateSyncFailed {
+    type: 'appStateSyncFailed';
+    fatal: string[];
+    retryable: string[];
+    skipped: string[];
+    connected: boolean;
+}
+/**
+ * An account-wide setting another linked device changed.
+ *
+ * Upstream reaches the same place through app state — `Utils/chat-utils.ts`
+ * emits `settings.update` for a `privacySettingDisableLinkPreviewsAction` —
+ * so this is that channel's payload arriving over a different pipe, not a
+ * new contract. The shape is the event's rather than one setting's: another
+ * setting the bridge starts reporting is a new arm here, not a new event.
+ */
+export interface CanonicalSettingUpdate {
+    type: 'settingUpdate';
+    setting: 'disableLinkPreviews';
+    value: proto.SyncActionValue.IPrivacySettingDisableLinkPreviewsAction;
+}
 export type CanonicalCallActionType = 'offer' | 'preaccept' | 'transport' | 'relaylatency' | 'accept' | 'reject' | 'terminate' | 'timeout';
 export interface CanonicalCallAction {
     type: CanonicalCallActionType;
@@ -654,5 +713,5 @@ export interface CanonicalServerAck {
     timestamp?: number;
     error?: string;
 }
-export type CanonicalEvent = CanonicalConnected | CanonicalDisconnected | CanonicalQR | CanonicalPairSuccess | CanonicalPairError | CanonicalLoggedOut | CanonicalConnectFailure | CanonicalStreamError | CanonicalStreamReplaced | CanonicalClientOutdated | CanonicalTemporaryBan | CanonicalQrScannedWithoutMultidevice | CanonicalMessage | CanonicalReceipt | CanonicalPushNameUpdate | CanonicalContactUpdate | CanonicalPictureUpdate | CanonicalPresence | CanonicalChatPresence | CanonicalGroupUpdate | CanonicalArchiveUpdate | CanonicalPinUpdate | CanonicalMuteUpdate | CanonicalStarUpdate | CanonicalMarkChatAsReadUpdate | CanonicalLabelEdit | CanonicalLabelAssociation | CanonicalIncomingCall | CanonicalUndecryptableMessage | CanonicalLidMappingUpdate | CanonicalNewsletterLiveUpdate | CanonicalChatDelete | CanonicalChatClear | CanonicalMessageDelete | CanonicalDisappearingModeChanged | CanonicalHistorySync | CanonicalOfflineSyncCompleted | CanonicalDirtyState | CanonicalRawNode | CanonicalNotification | CanonicalMexNotification | CanonicalServerAck | CanonicalNoop;
+export type CanonicalEvent = CanonicalConnected | CanonicalDisconnected | CanonicalQR | CanonicalPairSuccess | CanonicalPairError | CanonicalLoggedOut | CanonicalConnectFailure | CanonicalStreamError | CanonicalStreamReplaced | CanonicalClientOutdated | CanonicalTemporaryBan | CanonicalQrScannedWithoutMultidevice | CanonicalMessage | CanonicalReceipt | CanonicalPushNameUpdate | CanonicalContactUpdate | CanonicalPictureUpdate | CanonicalPresence | CanonicalChatPresence | CanonicalGroupUpdate | CanonicalArchiveUpdate | CanonicalPinUpdate | CanonicalMuteUpdate | CanonicalStarUpdate | CanonicalMarkChatAsReadUpdate | CanonicalLabelEdit | CanonicalLabelAssociation | CanonicalAppStateSyncFailed | CanonicalQrCodesExhausted | CanonicalSettingUpdate | CanonicalIncomingCall | CanonicalUndecryptableMessage | CanonicalLidMappingUpdate | CanonicalNewsletterLiveUpdate | CanonicalChatDelete | CanonicalChatClear | CanonicalMessageDelete | CanonicalDisappearingModeChanged | CanonicalHistorySync | CanonicalOfflineSyncCompleted | CanonicalDirtyState | CanonicalRawNode | CanonicalNotification | CanonicalMexNotification | CanonicalServerAck | CanonicalNoop;
 //# sourceMappingURL=types.d.ts.map