@whanext/core 0.19.18 → 0.19.20

package/dist/index.js

@@ -2346,7 +2346,23 @@ var WhaNextApp = class {
     const messaging = provider?.messaging ?? {
       sent: 0,
       received: 0,
-      failed: 0
+      failed: 0,
+      decryptedPayloads: 0,
+      unavailable: 0,
+      resendRequested: 0,
+      recovered: 0,
+      recoveryFailed: 0,
+      unavailableUnrecoverable: 0,
+      decodeFailures: 0,
+      unhandledStanzas: 0,
+      ignoredOffline: 0,
+      duplicates: 0,
+      normalizationFailures: 0,
+      transportFramesIn: 0,
+      transportNodesIn: 0,
+      transportDecodeErrors: 0,
+      messageStanzasIn: 0,
+      ingressStalls: 0
     };
     const crypto = provider?.crypto ?? {
       backend: "unknown",
@@ -2467,6 +2483,20 @@ var WhaNextApp = class {
         await this.#events.emit("groupMetadataRecovered", event.payload);
       } else if (event.type === "cryptoDegraded") {
         await this.#events.emit("cryptoDegraded", event.payload);
+      } else if (event.type === "messageUnavailable") {
+        await this.#events.emit("messageUnavailable", event.payload);
+      } else if (event.type === "messageRecovered") {
+        await this.#events.emit("messageRecovered", event.payload);
+      } else if (event.type === "messageRecoveryFailed") {
+        await this.#events.emit("messageRecoveryFailed", event.payload);
+      } else if (event.type === "messageDecodeFailure") {
+        await this.#events.emit("messageDecodeFailure", event.payload);
+      } else if (event.type === "messageDiscarded") {
+        await this.#events.emit("messageDiscarded", event.payload);
+      } else if (event.type === "messageIngressStalled") {
+        await this.#events.emit("messageIngressStalled", event.payload);
+      } else if (event.type === "transportDecodeFailure") {
+        await this.#events.emit("transportDecodeFailure", event.payload);
       }
       await this.#refreshHealthState();
     });
@@ -3136,11 +3166,14 @@ var sharedMediaProcessor = createMediaProcessor();
 var REMOTE_MEDIA_TIMEOUT_MS = 12e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 15e3;
 var DEFAULT_NODE_QUERY_TIMEOUT_MS = 3e4;
+var DEFAULT_INGRESS_STALL_TIMEOUT_MS = 1e4;
 var PROVIDER_DEGRADED_WINDOW_MS = 12e4;
 var GROUP_METADATA_CACHE_TTL_MS = 18e4;
 var DEVICE_LIST_CACHE_TTL_MS = 18e4;
 var GROUP_METADATA_RECOVERY_COOLDOWN_MS = 6e4;
 var GROUP_METADATA_MISMATCH_WARNING = "group message publish acknowledged with mismatch metadata";
+var MESSAGE_RECOVERY_TIMEOUT_MS = 3e4;
+var DECRYPT_CORRELATION_TTL_MS = 15e3;
 var messageSnapshotRetentionSeconds = 7 * 24 * 60 * 60;
 var messageSnapshotMaxPerSession = 2e4;
 var messageSnapshotPruneInterval = 256;
@@ -3151,6 +3184,9 @@ var ZapoProvider = class {
   #messageStore = /* @__PURE__ */ new Map();
   #messageKeyStore = /* @__PURE__ */ new WeakMap();
   #deliveredMessageStore = /* @__PURE__ */ new Set();
+  #pendingUnavailableRecoveries = /* @__PURE__ */ new Map();
+  #recentDecryptedPayloads = /* @__PURE__ */ new Map();
+  #pendingIngressMessages = /* @__PURE__ */ new Map();
   #handledProtocolStore = /* @__PURE__ */ new Set();
   #callCreatorStore = /* @__PURE__ */ new Map();
   #groupMetadataRecoveryAt = /* @__PURE__ */ new Map();
@@ -3159,6 +3195,8 @@ var ZapoProvider = class {
   #cryptoBackend;
   #connectTimeoutMs;
   #nodeQueryTimeoutMs;
+  #ingressDiagnostics;
+  #ingressStallTimeoutMs;
   #protocolMutationQueue = Promise.resolve();
   #state = "idle";
   #client;
@@ -3181,6 +3219,22 @@ var ZapoProvider = class {
   #sentMessages = 0;
   #receivedMessages = 0;
   #failedMessages = 0;
+  #decryptedPayloads = 0;
+  #unavailableMessages = 0;
+  #resendRequestedMessages = 0;
+  #recoveredMessages = 0;
+  #recoveryFailedMessages = 0;
+  #unavailableUnrecoverableMessages = 0;
+  #decodeFailures = 0;
+  #unhandledStanzas = 0;
+  #ignoredOfflineMessages = 0;
+  #duplicateMessages = 0;
+  #normalizationFailures = 0;
+  #transportFramesIn = 0;
+  #transportNodesIn = 0;
+  #transportDecodeErrors = 0;
+  #messageStanzasIn = 0;
+  #ingressStalls = 0;
   #lastIncomingAt;
   #lastOutgoingAt;
   #decryptFailures = 0;
@@ -3198,6 +3252,8 @@ var ZapoProvider = class {
     this.#messageCacheSize = Math.max(1, options.messageCacheSize ?? 1e3);
     this.#connectTimeoutMs = normalizeProviderTimeout(options.connectTimeoutMs, DEFAULT_CONNECT_TIMEOUT_MS);
     this.#nodeQueryTimeoutMs = normalizeProviderTimeout(options.nodeQueryTimeoutMs, DEFAULT_NODE_QUERY_TIMEOUT_MS);
+    this.#ingressDiagnostics = options.ingressDiagnostics === true;
+    this.#ingressStallTimeoutMs = normalizeProviderTimeout(options.ingressStallTimeoutMs, DEFAULT_INGRESS_STALL_TIMEOUT_MS);
     this.#cryptoBackend = detectCryptoBackend();
   }
   on(event, listener) {
@@ -3221,6 +3277,22 @@ var ZapoProvider = class {
         sent: this.#sentMessages,
         received: this.#receivedMessages,
         failed: this.#failedMessages,
+        decryptedPayloads: this.#decryptedPayloads,
+        unavailable: this.#unavailableMessages,
+        resendRequested: this.#resendRequestedMessages,
+        recovered: this.#recoveredMessages,
+        recoveryFailed: this.#recoveryFailedMessages,
+        unavailableUnrecoverable: this.#unavailableUnrecoverableMessages,
+        decodeFailures: this.#decodeFailures,
+        unhandledStanzas: this.#unhandledStanzas,
+        ignoredOffline: this.#ignoredOfflineMessages,
+        duplicates: this.#duplicateMessages,
+        normalizationFailures: this.#normalizationFailures,
+        transportFramesIn: this.#transportFramesIn,
+        transportNodesIn: this.#transportNodesIn,
+        transportDecodeErrors: this.#transportDecodeErrors,
+        messageStanzasIn: this.#messageStanzasIn,
+        ingressStalls: this.#ingressStalls,
         ...this.#lastIncomingAt ? { lastIncomingAt: new Date(this.#lastIncomingAt) } : {},
         ...this.#lastOutgoingAt ? { lastOutgoingAt: new Date(this.#lastOutgoingAt) } : {}
       },
@@ -3267,6 +3339,15 @@ var ZapoProvider = class {
       clearTimeout(this.#healthRefreshTimer);
       this.#healthRefreshTimer = void 0;
     }
+    for (const pending of this.#pendingUnavailableRecoveries.values()) {
+      clearTimeout(pending.timer);
+    }
+    this.#pendingUnavailableRecoveries.clear();
+    for (const pending of this.#pendingIngressMessages.values()) {
+      clearTimeout(pending.timer);
+    }
+    this.#pendingIngressMessages.clear();
+    this.#recentDecryptedPayloads.clear();
     const client = this.#client;
     this.#connectPromise = void 0;
     try {
@@ -3605,7 +3686,22 @@ var ZapoProvider = class {
       );
       void this.#stopTerminalConnection(client, error);
     });
+    client.on("debug_transport_frame_in", ({ frame }) => {
+      this.#transportFramesIn += 1;
+      if (this.#ingressDiagnostics) {
+        this.#logger.debug("Inbound WhatsApp transport frame received.", {
+          frameBytes: frame.byteLength
+        });
+      }
+    });
+    client.on("debug_transport_node_in", ({ node }) => {
+      this.#handleTransportNodeIn(node);
+    });
+    client.on("debug_transport_decode_error", ({ error, frame }) => {
+      this.#handleTransportDecodeError(error, frame.byteLength);
+    });
     client.on("message", (event) => {
+      this.#resolveIngressMessage(event.key, "message_event");
       const protocol = this.#protocolMessage(event);
       if (protocol && this.#isMessageMutationProtocol(protocol.type)) {
         this.#enqueueProtocolEvent({
@@ -3628,6 +3724,16 @@ var ZapoProvider = class {
       }
       this.#handleMessage(event);
     });
+    client.on("message_unavailable", (event) => {
+      this.#resolveIngressMessage(event.key, "unavailable");
+      this.#handleUnavailableMessage(event);
+    });
+    client.on("debug_decrypted_payload", (event) => {
+      this.#handleDecryptedPayload(event);
+    });
+    client.on("debug_unhandled_stanza", (event) => {
+      this.#handleUnhandledStanza(event);
+    });
     client.on("message_send", (event) => {
       if (!event.id || !event.message) return;
       this.#sentMessages += 1;
@@ -3659,6 +3765,139 @@ var ZapoProvider = class {
       void this.#handleConnectionEvent(client, event);
     });
   }
+  #handleTransportNodeIn(node) {
+    this.#transportNodesIn += 1;
+    if (node.tag !== "message") return;
+    this.#messageStanzasIn += 1;
+    const stanzaId = stringValue(node.attrs.id);
+    const chatId = normalizeIngressJid(stringValue(node.attrs.from));
+    const participantId = normalizeIngressJid(
+      stringValue(node.attrs.participant) ?? stringValue(node.attrs.participant_pn) ?? stringValue(node.attrs.participant_lid) ?? stringValue(node.attrs.sender_pn) ?? stringValue(node.attrs.sender_lid)
+    );
+    const stanzaType = stringValue(node.attrs.type);
+    const addressingMode = stringValue(node.attrs.addressing_mode);
+    const children = Array.isArray(node.content) ? node.content : [];
+    const childTags = [...new Set(children.map((child) => child.tag))];
+    const encTypes = [...new Set(children.filter((child) => child.tag === "enc").map((child) => stringValue(child.attrs.type)).filter((value) => value !== void 0))];
+    if (this.#ingressDiagnostics) {
+      this.#logger.info("Inbound WhatsApp message stanza observed.", {
+        ...stanzaId ? { stanzaId } : {},
+        ...chatId ? { chatId } : {},
+        ...participantId ? { participantId } : {},
+        ...stanzaType ? { stanzaType } : {},
+        ...addressingMode ? { addressingMode } : {},
+        ...childTags.length > 0 ? { childTags } : {},
+        ...encTypes.length > 0 ? { encTypes } : {}
+      });
+    }
+    const correlationKey = this.#stanzaCorrelationKey(chatId, stanzaId);
+    if (!correlationKey || !stanzaId) return;
+    const previous = this.#pendingIngressMessages.get(correlationKey);
+    if (previous) clearTimeout(previous.timer);
+    const observedAt = Date.now();
+    const timer = setTimeout(() => {
+      const pending = this.#pendingIngressMessages.get(correlationKey);
+      if (!pending || pending.observedAt !== observedAt) return;
+      this.#pendingIngressMessages.delete(correlationKey);
+      this.#ingressStalls += 1;
+      this.#markDegraded();
+      const occurredAt = /* @__PURE__ */ new Date();
+      this.#emitStability({
+        type: "messageIngressStalled",
+        payload: {
+          occurredAt,
+          waitedMs: occurredAt.getTime() - pending.observedAt,
+          lastStage: pending.lastStage,
+          stanzaId: pending.stanzaId,
+          ...pending.chatId ? { chatId: pending.chatId } : {},
+          ...pending.participantId ? { participantId: pending.participantId } : {},
+          ...pending.stanzaType ? { stanzaType: pending.stanzaType } : {},
+          ...pending.addressingMode ? { addressingMode: pending.addressingMode } : {}
+        }
+      });
+      this.#logger.warn("Inbound WhatsApp message stanza did not reach a terminal provider event.", {
+        stanzaId: pending.stanzaId,
+        ...pending.chatId ? { chatId: pending.chatId } : {},
+        ...pending.participantId ? { participantId: pending.participantId } : {},
+        lastStage: pending.lastStage,
+        waitedMs: occurredAt.getTime() - pending.observedAt
+      });
+    }, this.#ingressStallTimeoutMs);
+    this.#pendingIngressMessages.set(correlationKey, {
+      observedAt,
+      lastStage: "stanza_received",
+      timer,
+      stanzaId,
+      ...chatId ? { chatId } : {},
+      ...participantId ? { participantId } : {},
+      ...stanzaType ? { stanzaType } : {},
+      ...addressingMode ? { addressingMode } : {}
+    });
+  }
+  #handleTransportDecodeError(error, frameBytes) {
+    this.#transportDecodeErrors += 1;
+    this.#markDegraded();
+    const occurredAt = /* @__PURE__ */ new Date();
+    this.#emitStability({
+      type: "transportDecodeFailure",
+      payload: {
+        occurredAt,
+        frameBytes,
+        errorName: error.name || "Error",
+        errorMessage: error.message || String(error)
+      }
+    });
+    this.#logger.warn("Inbound WhatsApp transport frame could not be decoded.", {
+      frameBytes,
+      errorName: error.name || "Error",
+      errorMessage: error.message || String(error)
+    });
+  }
+  #markIngressDecrypted(chatId, stanzaId) {
+    const correlationKey = this.#stanzaCorrelationKey(normalizeIngressJid(chatId), stanzaId);
+    if (!correlationKey) return;
+    const pending = this.#pendingIngressMessages.get(correlationKey);
+    if (!pending) return;
+    pending.lastStage = "decrypted";
+    if (this.#ingressDiagnostics) {
+      this.#logger.info("Inbound WhatsApp message payload decrypted.", {
+        stanzaId: pending.stanzaId,
+        ...pending.chatId ? { chatId: pending.chatId } : {},
+        ...pending.participantId ? { participantId: pending.participantId } : {}
+      });
+    }
+  }
+  #resolveIngressMessage(key, outcome) {
+    const chatId = normalizeIngressJid(key.remoteJid ?? void 0);
+    const correlationKey = this.#stanzaCorrelationKey(chatId, key.id ?? void 0);
+    if (!correlationKey) return;
+    const pending = this.#pendingIngressMessages.get(correlationKey);
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    this.#pendingIngressMessages.delete(correlationKey);
+    if (this.#ingressDiagnostics) {
+      this.#logger.info("Inbound WhatsApp message stanza reached provider terminal stage.", {
+        stanzaId: pending.stanzaId,
+        ...pending.chatId ? { chatId: pending.chatId } : {},
+        ...pending.participantId ? { participantId: pending.participantId } : {},
+        lastStage: pending.lastStage,
+        outcome,
+        durationMs: Date.now() - pending.observedAt
+      });
+    }
+  }
+  #resolveIngressByStanza(chatId, stanzaId, outcome) {
+    const normalizedChatId = normalizeIngressJid(chatId);
+    const correlationKey = this.#stanzaCorrelationKey(normalizedChatId, stanzaId);
+    if (!correlationKey) return;
+    const pending = this.#pendingIngressMessages.get(correlationKey);
+    if (!pending) return;
+    const remoteJid = pending.chatId ?? normalizedChatId;
+    this.#resolveIngressMessage({
+      id: pending.stanzaId,
+      ...remoteJid ? { remoteJid } : {}
+    }, outcome);
+  }
   #handleMessage(event) {
     const stored = event;
     if (stored.key?.id && stored.message) this.#remember(stored);
@@ -3666,7 +3905,16 @@ var ZapoProvider = class {
     if (quoted?.key.id && quoted.message) {
       this.#remember(quoted);
     }
+    const deliveryKey = this.#messageDeliveryKey(stored.key);
+    this.#resolveUnavailableRecovery(deliveryKey, stored.key);
+    const decryptedCorrelationKey = this.#stanzaCorrelationKey(
+      normalizeIngressJid(stored.key.remoteJid ?? void 0),
+      stored.key.id ?? void 0
+    );
+    if (decryptedCorrelationKey) this.#recentDecryptedPayloads.delete(decryptedCorrelationKey);
     if (this.#isOfflineMessage(stored)) {
+      this.#ignoredOfflineMessages += 1;
+      this.#emitMessageDiscarded("offline", stored.key);
       this.#logger.debug("Ignored message queued before the current live connection.", {
         messageId: stored.key.id ?? void 0,
         chatId: stored.key.remoteJid ?? void 0,
@@ -3674,8 +3922,9 @@ var ZapoProvider = class {
       });
       return;
     }
-    const deliveryKey = this.#messageDeliveryKey(stored.key);
     if (stored.key.id && this.#deliveredMessageStore.has(deliveryKey)) {
+      this.#duplicateMessages += 1;
+      this.#emitMessageDiscarded("duplicate", stored.key);
       this.#logger.debug("Ignored duplicate Zapo message event.", {
         messageId: stored.key.id,
         chatId: stored.key.remoteJid ?? void 0
@@ -3683,10 +3932,28 @@ var ZapoProvider = class {
       return;
     }
     const message = normalizeZapoMessage(event);
-    if (!message) return;
+    if (!message) {
+      this.#normalizationFailures += 1;
+      this.#emitMessageDiscarded("normalization_failed", stored.key);
+      this.#logger.warn("Could not normalize incoming Zapo message.", {
+        messageId: stored.key.id ?? void 0,
+        chatId: stored.key.remoteJid ?? void 0
+      });
+      return;
+    }
     if (stored.key.id) this.#rememberDeliveredMessage(deliveryKey);
     this.#receivedMessages += 1;
     this.#lastIncomingAt = /* @__PURE__ */ new Date();
+    if (this.#ingressDiagnostics) {
+      this.#logger.info("Inbound WhatsApp message emitted to WhaNext.", {
+        messageId: message.id,
+        chatId: message.chatId,
+        userId: message.sender.id,
+        contentKind: message.contentKind,
+        hasMedia: message.media !== void 0,
+        hasQuoted: message.quoted !== void 0
+      });
+    }
     this.#messageKeyStore.set(message.keys, stored);
     if (message.quoted && quoted?.message) {
       this.#messageKeyStore.set(
@@ -3696,6 +3963,166 @@ var ZapoProvider = class {
     }
     void this.#events.emit("message", message);
   }
+  #handleUnavailableMessage(event) {
+    this.#unavailableMessages += 1;
+    const occurredAt = /* @__PURE__ */ new Date();
+    const messageId = event.key.id || void 0;
+    const chatId = event.key.remoteJid || void 0;
+    const participantId = event.key.participant ?? event.key.participantAlt ?? void 0;
+    this.#emitStability({
+      type: "messageUnavailable",
+      payload: {
+        kind: event.kind,
+        resendRequested: event.resendRequested,
+        occurredAt,
+        ...messageId ? { messageId } : {},
+        ...chatId ? { chatId } : {},
+        ...participantId ? { participantId } : {}
+      }
+    });
+    if (!event.resendRequested) {
+      this.#unavailableUnrecoverableMessages += 1;
+      const log = event.kind === "other" ? this.#logger.warn.bind(this.#logger) : this.#logger.debug.bind(this.#logger);
+      log("Incoming message is unavailable and was not queued for recovery.", {
+        kind: event.kind,
+        ...messageId ? { messageId } : {},
+        ...chatId ? { chatId } : {},
+        ...participantId ? { participantId } : {}
+      });
+      return;
+    }
+    this.#resendRequestedMessages += 1;
+    const deliveryKey = this.#messageDeliveryKey(event.key);
+    const previous = this.#pendingUnavailableRecoveries.get(deliveryKey);
+    if (previous) clearTimeout(previous.timer);
+    const requestedAt = Date.now();
+    const timer = setTimeout(() => {
+      const pending = this.#pendingUnavailableRecoveries.get(deliveryKey);
+      if (!pending || pending.requestedAt !== requestedAt) return;
+      this.#pendingUnavailableRecoveries.delete(deliveryKey);
+      this.#recoveryFailedMessages += 1;
+      this.#markDegraded();
+      const failedAt = /* @__PURE__ */ new Date();
+      this.#emitStability({
+        type: "messageRecoveryFailed",
+        payload: {
+          failedAt,
+          waitedMs: failedAt.getTime() - pending.requestedAt,
+          ...pending.messageId ? { messageId: pending.messageId } : {},
+          ...pending.chatId ? { chatId: pending.chatId } : {},
+          ...pending.participantId ? { participantId: pending.participantId } : {}
+        }
+      });
+      this.#logger.warn("Unavailable message recovery did not arrive in time.", {
+        ...pending.messageId ? { messageId: pending.messageId } : {},
+        ...pending.chatId ? { chatId: pending.chatId } : {},
+        waitedMs: failedAt.getTime() - pending.requestedAt
+      });
+    }, MESSAGE_RECOVERY_TIMEOUT_MS);
+    this.#pendingUnavailableRecoveries.set(deliveryKey, {
+      requestedAt,
+      timer,
+      ...messageId ? { messageId } : {},
+      ...chatId ? { chatId } : {},
+      ...participantId ? { participantId } : {}
+    });
+    this.#logger.info("Incoming message unavailable; primary-device resend requested.", {
+      ...messageId ? { messageId } : {},
+      ...chatId ? { chatId } : {},
+      ...participantId ? { participantId } : {}
+    });
+  }
+  #resolveUnavailableRecovery(deliveryKey, key) {
+    const pending = this.#pendingUnavailableRecoveries.get(deliveryKey);
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    this.#pendingUnavailableRecoveries.delete(deliveryKey);
+    this.#recoveredMessages += 1;
+    const recoveredAt = /* @__PURE__ */ new Date();
+    const participantId = key.participant ?? key.participantAlt ?? pending.participantId;
+    this.#emitStability({
+      type: "messageRecovered",
+      payload: {
+        recoveredAt,
+        recoveryMs: recoveredAt.getTime() - pending.requestedAt,
+        ...key.id ? { messageId: key.id } : pending.messageId ? { messageId: pending.messageId } : {},
+        ...key.remoteJid ? { chatId: key.remoteJid } : pending.chatId ? { chatId: pending.chatId } : {},
+        ...participantId ? { participantId } : {}
+      }
+    });
+    this.#logger.info("Recovered unavailable message from the primary device.", {
+      ...key.id ? { messageId: key.id } : {},
+      ...key.remoteJid ? { chatId: key.remoteJid } : {},
+      recoveryMs: recoveredAt.getTime() - pending.requestedAt
+    });
+  }
+  #handleDecryptedPayload(event) {
+    this.#decryptedPayloads += 1;
+    this.#markIngressDecrypted(event.chatJid, event.stanzaId);
+    const correlationKey = this.#stanzaCorrelationKey(normalizeIngressJid(event.chatJid), event.stanzaId);
+    if (!correlationKey) return;
+    const now = Date.now();
+    this.#recentDecryptedPayloads.set(correlationKey, {
+      observedAt: now,
+      encType: event.encType
+    });
+    for (const [key, value] of this.#recentDecryptedPayloads) {
+      if (now - value.observedAt > DECRYPT_CORRELATION_TTL_MS) {
+        this.#recentDecryptedPayloads.delete(key);
+      }
+    }
+  }
+  #handleUnhandledStanza(event) {
+    this.#unhandledStanzas += 1;
+    const normalizedChatId = normalizeIngressJid(event.chatJid);
+    const correlationKey = this.#stanzaCorrelationKey(normalizedChatId, event.stanzaId);
+    const decrypted = correlationKey ? this.#recentDecryptedPayloads.get(correlationKey) : void 0;
+    const now = Date.now();
+    if (decrypted && now - decrypted.observedAt <= DECRYPT_CORRELATION_TTL_MS) {
+      this.#decodeFailures += 1;
+      this.#resolveIngressByStanza(normalizedChatId, event.stanzaId, "decode_failure");
+      this.#markDegraded();
+      this.#emitStability({
+        type: "messageDecodeFailure",
+        payload: {
+          occurredAt: new Date(now),
+          reason: event.reason,
+          encType: decrypted.encType,
+          ...event.stanzaId ? { stanzaId: event.stanzaId } : {},
+          ...event.chatJid ? { chatId: event.chatJid } : {}
+        }
+      });
+      this.#logger.warn("Decrypted incoming payload could not be decoded into a supported stanza.", {
+        reason: event.reason,
+        encType: decrypted.encType,
+        ...event.stanzaId ? { stanzaId: event.stanzaId } : {},
+        ...event.chatJid ? { chatId: event.chatJid } : {}
+      });
+      if (correlationKey) this.#recentDecryptedPayloads.delete(correlationKey);
+      return;
+    }
+    this.#resolveIngressByStanza(normalizedChatId, event.stanzaId, "decode_failure");
+    this.#logger.debug("Incoming stanza was not handled by Zapo.", {
+      reason: event.reason,
+      ...event.stanzaId ? { stanzaId: event.stanzaId } : {},
+      ...event.chatJid ? { chatId: event.chatJid } : {}
+    });
+  }
+  #emitMessageDiscarded(reason, key) {
+    this.#emitStability({
+      type: "messageDiscarded",
+      payload: {
+        reason,
+        occurredAt: /* @__PURE__ */ new Date(),
+        ...key.id ? { messageId: key.id } : {},
+        ...key.remoteJid ? { chatId: key.remoteJid } : {}
+      }
+    });
+  }
+  #stanzaCorrelationKey(chatJid, stanzaId) {
+    if (!stanzaId) return void 0;
+    return `${chatJid ?? ""}:${stanzaId}`;
+  }
   #handleAddonEvent(event) {
     const decrypted = this.#addonRecord(event.decrypted);
     const protocol = this.#addonProtocolMessage(decrypted);
@@ -3953,6 +4380,11 @@ var ZapoProvider = class {
     }
     if (message === "failed to decrypt incoming message") {
       this.#decryptFailures += 1;
+      this.#resolveIngressByStanza(
+        stringValue(context.from) ?? stringValue(context.groupJid),
+        stringValue(context.id),
+        "decrypt_failure"
+      );
       const detail = stringValue(context.message);
       const kind = detail === "sender key id mismatch" ? "sender_key_mismatch" : "decrypt_failure";
       if (kind === "sender_key_mismatch") this.#senderKeyMismatches += 1;
@@ -4433,11 +4865,16 @@ var ZapoProvider = class {
     return mentions.map((mention) => typeof mention === "string" ? mention : mention.mentionId);
   }
   #toZapoKey(key) {
+    const original = this.#messageKeyStore.get(key)?.key;
+    const participant = original?.participant ?? key.participantId;
     return {
       id: key.id,
       remoteJid: key.chatId,
       fromMe: key.fromMe,
-      ...key.participantId ? { participant: key.participantId } : {}
+      ...original?.remoteJidAlt ? { remoteJidAlt: original.remoteJidAlt } : {},
+      ...participant ? { participant } : {},
+      ...original?.participantAlt ? { participantAlt: original.participantAlt } : {},
+      ...original?.addressingMode ? { addressingMode: original.addressingMode } : {}
     };
   }
   #sent(result, chatId) {
@@ -5113,6 +5550,13 @@ function normalizeProviderTimeout(value, fallback) {
   if (value === void 0 || !Number.isFinite(value)) return fallback;
   return Math.max(1e3, Math.floor(value));
 }
+function normalizeIngressJid(value) {
+  if (!value) return void 0;
+  const at = value.indexOf("@");
+  if (at <= 0) return value;
+  const local = value.slice(0, at).replace(/:\d+$/, "");
+  return `${local}${value.slice(at)}`;
+}
 function detectCryptoBackend() {
   const requested = process.env.ZAPO_NATIVE_BACKEND?.trim().toLowerCase() ?? "auto";
   if (requested === "js" || requested === "none") return "js";
@@ -5213,7 +5657,9 @@ async function create(options = {}) {
     ...options.processOfflineMessages !== void 0 ? { processOfflineMessages: options.processOfflineMessages } : {},
     ...options.reconnect ? { reconnect: options.reconnect } : {},
     ...options.providerTimeouts?.connectTimeoutMs !== void 0 ? { connectTimeoutMs: options.providerTimeouts.connectTimeoutMs } : {},
-    ...options.providerTimeouts?.nodeQueryTimeoutMs !== void 0 ? { nodeQueryTimeoutMs: options.providerTimeouts.nodeQueryTimeoutMs } : {}
+    ...options.providerTimeouts?.nodeQueryTimeoutMs !== void 0 ? { nodeQueryTimeoutMs: options.providerTimeouts.nodeQueryTimeoutMs } : {},
+    ...options.providerDiagnostics?.ingress !== void 0 ? { ingressDiagnostics: options.providerDiagnostics.ingress } : {},
+    ...options.providerDiagnostics?.ingressStallTimeoutMs !== void 0 ? { ingressStallTimeoutMs: options.providerDiagnostics.ingressStallTimeoutMs } : {}
   });
   return new WhaNextApp(provider, {
     ...options.accountId ? { accountId: options.accountId } : {},
@@ -5451,6 +5897,12 @@ function mergeCreateOptions(shared, account) {
       ...account.providerTimeouts
     };
   }
+  if (shared.providerDiagnostics || account.providerDiagnostics) {
+    merged.providerDiagnostics = {
+      ...shared.providerDiagnostics,
+      ...account.providerDiagnostics
+    };
+  }
   if (shared.logger && account.logger && typeof shared.logger === "object" && typeof account.logger === "object") {
     merged.logger = {
       ...shared.logger,