@whanext/core 0.19.18 → 0.19.19

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.19.19
+
+### Provider
+- Updated the official provider from `zapo-js@1.7.1` to `zapo-js@1.8.0`.
+- Kept full received LID/PN addressing metadata when replying, reacting, editing, revoking, and pinning messages.
+- Inherits Zapo 1.8.0 mailbox `fromMe` persistence fixes, group-status stanza attribute unwrapping, username support, expired-CDN media resend support, and mobile-primary WhatsApp Business support.
+
+### Incoming message observability
+- Added `message_unavailable` tracking with primary-device resend correlation and a bounded 30-second recovery window.
+- Added `debug_decrypted_payload` correlation with `debug_unhandled_stanza` so decrypted-but-undecodable payloads are visible without logging plaintext bytes.
+- Expanded `health().messaging` with `decryptedPayloads`, `unavailable`, `resendRequested`, `recovered`, `recoveryFailed`, `unavailableUnrecoverable`, `decodeFailures`, `unhandledStanzas`, `ignoredOffline`, `duplicates`, and `normalizationFailures`.
+- Added typed `messageUnavailable`, `messageRecovered`, `messageRecoveryFailed`, `messageDecodeFailure`, and `messageDiscarded` application events.
+- Recovery failures and decrypted-payload decode failures temporarily mark provider stability as `degraded`; expected unrecoverable placeholders such as consumed view-once messages are counted without automatically degrading the session.
+
+### Safety
+- Raw decrypted payload bytes from Zapo are never emitted through the WhaNext public events or written to logs.
+- Existing `received`, `sent`, and `failed` counters keep their previous semantics; the new counters explain why an inbound stanza may not have become a public WhaNext `Message`.
+
 ## 0.19.18
 
 ### Stability

package/README.md

@@ -331,7 +331,21 @@ console.log(health.timeouts);
 
 `status` continua representando o ciclo da aplicação: `idle`, `starting`, `ready` ou `stopped`. `stability` representa a saúde operacional do provider: `healthy`, `degraded`, `reconnecting` ou `offline`.
 
-O provider Zapo contabiliza reconexões, mensagens enviadas/recebidas, falhas de envio, falhas de descriptografia, `sender key id mismatch`, falhas de addons, divergências de `phash` e recuperações de metadata. O router contabiliza execuções ativas, fila atual, expirações e rejeições por fila cheia.
+O provider Zapo contabiliza reconexões, mensagens enviadas/recebidas, falhas de envio, falhas de descriptografia, `sender key id mismatch`, falhas de addons, divergências de `phash` e recuperações de metadata. Com Zapo 1.8.0, `health.messaging` também mostra mensagens indisponíveis, pedidos de resend, recuperações, payloads descriptografados, falhas de decode, stanzas não tratadas, duplicatas, mensagens offline ignoradas e falhas de normalização. O router contabiliza execuções ativas, fila atual, expirações e rejeições por fila cheia.
+
+```ts
+const { messaging } = app.health();
+
+console.log(messaging.unavailable);
+console.log(messaging.resendRequested);
+console.log(messaging.recovered);
+console.log(messaging.recoveryFailed);
+console.log(messaging.decodeFailures);
+console.log(messaging.ignoredOffline);
+console.log(messaging.duplicates);
+```
+
+`decryptedPayloads` conta payloads `<enc>` individuais, portanto pode ser maior que `received` em fanout para vários devices. O WhaNext usa esse sinal apenas para correlação e nunca expõe os bytes descriptografados no health, eventos públicos ou logs.
 
 ```ts
 server.get('/health', async () => app.health());
@@ -390,6 +404,26 @@ app.on('cryptoDegraded', ({ kind, chatId }) => {
   console.log(kind, chatId);
 });
 
+app.on('messageUnavailable', ({ messageId, resendRequested }) => {
+  console.log(messageId, resendRequested);
+});
+
+app.on('messageRecovered', ({ messageId, recoveryMs }) => {
+  console.log(messageId, recoveryMs);
+});
+
+app.on('messageRecoveryFailed', ({ messageId, waitedMs }) => {
+  console.log(messageId, waitedMs);
+});
+
+app.on('messageDecodeFailure', ({ stanzaId, reason }) => {
+  console.log(stanzaId, reason);
+});
+
+app.on('messageDiscarded', ({ messageId, reason }) => {
+  console.log(messageId, reason);
+});
+
 app.on('commandQueueTimeout', ({ command, queuedForMs }) => {
   console.log(command, queuedForMs);
 });

package/dist/index.d.ts

@@ -315,6 +315,17 @@ interface ProviderMessagingHealth {
     sent: number;
     received: number;
     failed: number;
+    decryptedPayloads: number;
+    unavailable: number;
+    resendRequested: number;
+    recovered: number;
+    recoveryFailed: number;
+    unavailableUnrecoverable: number;
+    decodeFailures: number;
+    unhandledStanzas: number;
+    ignoredOffline: number;
+    duplicates: number;
+    normalizationFailures: number;
     lastIncomingAt?: Date;
     lastOutgoingAt?: Date;
 }
@@ -354,12 +365,63 @@ interface CryptoDegradedEvent {
     chatId?: string;
     participantId?: string;
 }
+interface MessageUnavailableEvent {
+    kind: 'view_once' | 'hosted' | 'bot' | 'other';
+    resendRequested: boolean;
+    occurredAt: Date;
+    messageId?: string;
+    chatId?: string;
+    participantId?: string;
+}
+interface MessageRecoveredEvent {
+    recoveredAt: Date;
+    recoveryMs: number;
+    messageId?: string;
+    chatId?: string;
+    participantId?: string;
+}
+interface MessageRecoveryFailedEvent {
+    failedAt: Date;
+    waitedMs: number;
+    messageId?: string;
+    chatId?: string;
+    participantId?: string;
+}
+interface MessageDecodeFailureEvent {
+    occurredAt: Date;
+    reason: string;
+    stanzaId?: string;
+    chatId?: string;
+    encType?: string;
+}
+type MessageDiscardReason = 'offline' | 'duplicate' | 'normalization_failed';
+interface MessageDiscardedEvent {
+    reason: MessageDiscardReason;
+    occurredAt: Date;
+    messageId?: string;
+    chatId?: string;
+}
 type ProviderStabilityEvent = {
     type: 'groupMetadataRecovered';
     payload: GroupMetadataRecoveredEvent;
 } | {
     type: 'cryptoDegraded';
     payload: CryptoDegradedEvent;
+} | {
+    type: 'messageUnavailable';
+    payload: MessageUnavailableEvent;
+} | {
+    type: 'messageRecovered';
+    payload: MessageRecoveredEvent;
+} | {
+    type: 'messageRecoveryFailed';
+    payload: MessageRecoveryFailedEvent;
+} | {
+    type: 'messageDecodeFailure';
+    payload: MessageDecodeFailureEvent;
+} | {
+    type: 'messageDiscarded';
+    payload: MessageDiscardedEvent;
 } | {
     type: 'healthRefresh';
     payload: {
@@ -936,6 +998,11 @@ interface AppEvents {
     connectionRecovered: ConnectionRecoveredEvent;
     groupMetadataRecovered: GroupMetadataRecoveredEvent;
     cryptoDegraded: CryptoDegradedEvent;
+    messageUnavailable: MessageUnavailableEvent;
+    messageRecovered: MessageRecoveredEvent;
+    messageRecoveryFailed: MessageRecoveryFailedEvent;
+    messageDecodeFailure: MessageDecodeFailureEvent;
+    messageDiscarded: MessageDiscardedEvent;
     commandQueueTimeout: CommandQueueTimeoutEvent;
     commandQueueFull: CommandQueueFullEvent;
 }
@@ -1105,4 +1172,4 @@ declare class SqliteMuteStore implements MuteStore {
     close(): void;
 }
 
-export { AccountService, type AddMuteOptions, type AddMuteResult, type AppEvents, type AppHealth, type AppHealthStatus, ArgsParser, type AudioContent, type BooleanOption, Browser, type ButtonsContent, type CacheOptions, type CacheStore, type CallEvent, type CallStatus, type ChangeResult, type CommandAccountContext, type CommandCatalogOptions, type CommandCatalogView, type CommandChatContext, type CommandConcurrency, type CommandConcurrencyContext, type CommandConcurrencyEvent, type CommandConcurrencyHealth, type CommandContext, type CommandCooldown, type CommandDefinition, type CommandErrorHandler, type CommandGroupContext, type CommandGroupDefinition, type CommandGuard, type CommandHelpOptions, type CommandHooks, type CommandLocalization, type CommandMetadata, type CommandMiddleware, type CommandOptionDefinition, type CommandOptionSchema, type CommandOptionValue, type CommandOptionValues, type CommandQueueFullEvent, type CommandQueueTimeoutEvent, type CommandRegistrar, CommandRouter, type CommandRouterEvents, type CommandRuntimeServices, type CommandScope, type ConcurrencyStrategy, type ConnectionRecoveredEvent, type ConnectionState, type ConnectionUpdate, type CopyCodeButton, type CreateMultiOptions, type CreateOptions, type CryptoAccelerationBackend, type CryptoDegradationKind, type CryptoDegradedEvent, DeferredReply, type DownloadedMedia, type DurationOption, type EnumOption, type ExecutableCommandDefinition, type GroupAccess, type GroupAddressingMode, type GroupMetadataRecoveredEvent, type GroupParticipant, type GroupParticipantAction, type GroupParticipantsChanged, type GroupRole, type GroupSnapshot, type GuardResult, type HealthChangedEvent, type ImageContent, type InteractiveResponse, type InteractiveResponseKind, type InviteResult, type LinkButton, type ListContent, type ListRow, type ListSection, type LoadCommandsOptions, type LoadCommandsResult, type LoadedCommand, type LogContext, type LogEntry, type LogFormat, type LogLevel, type LogWriter, Logger, type LoggerConfig, type LoggerOptions, type LoginOptions, type MediaKind, type MediaSource, type MemberActionState, MemoryCache, type MemoryCacheStats, type MentionTarget, type Message, type MessageButton, type MessageContent, type MessageContentKind, type MessageDeleted, type MessageEdited, type MessageKey, type MessageMedia, type MessagePayloadKind, type MessageProtocolKind, type MultiAccountOptions, type MultiAppEvent, type MultiAppHealth, MultiCommandRouter, type MultiLoadCommandsResult, type MultiLoginOptions, type MuteChangeResult, type MuteEnforcement, type MuteOptions, type MuteRecord, MuteService, type MuteStore, type NumberOption, ParsedCommandOptions, type ParticipantUpdateResult, type PollContent, type PresenceState, type ProviderConnectionHealth, type ProviderCryptoHealth, type ProviderGroupHealth, type ProviderHealth, type ProviderMessagingHealth, type ProviderStabilityEvent, type ProviderTimeoutHealth, type ProviderTimeoutOptions, type QuickReplyButton, type QuotedMessage, type ReconnectOptions, type RegisteredCommand, type RemoveMuteResult, type ReplyOptions, type RepostMessageOptions, type RouterOptions, type SentMessage, SqliteMuteStore, type StabilityHealthStatus, type StickerContent, type StoredMute, type StringOption, type TextContent, User, type UserData, type UserOption, type VideoContent, WhaNextApp, WhaNextError, type WhaNextErrorCode, WhaNextMultiApp, type WhatsAppProvider, create, createMulti, defineCommand, defineCommandGroup, defineCommands, defineSubcommand, guards, isCommandGroup, loadCommands, option, toWhaNextError };
+export { AccountService, type AddMuteOptions, type AddMuteResult, type AppEvents, type AppHealth, type AppHealthStatus, ArgsParser, type AudioContent, type BooleanOption, Browser, type ButtonsContent, type CacheOptions, type CacheStore, type CallEvent, type CallStatus, type ChangeResult, type CommandAccountContext, type CommandCatalogOptions, type CommandCatalogView, type CommandChatContext, type CommandConcurrency, type CommandConcurrencyContext, type CommandConcurrencyEvent, type CommandConcurrencyHealth, type CommandContext, type CommandCooldown, type CommandDefinition, type CommandErrorHandler, type CommandGroupContext, type CommandGroupDefinition, type CommandGuard, type CommandHelpOptions, type CommandHooks, type CommandLocalization, type CommandMetadata, type CommandMiddleware, type CommandOptionDefinition, type CommandOptionSchema, type CommandOptionValue, type CommandOptionValues, type CommandQueueFullEvent, type CommandQueueTimeoutEvent, type CommandRegistrar, CommandRouter, type CommandRouterEvents, type CommandRuntimeServices, type CommandScope, type ConcurrencyStrategy, type ConnectionRecoveredEvent, type ConnectionState, type ConnectionUpdate, type CopyCodeButton, type CreateMultiOptions, type CreateOptions, type CryptoAccelerationBackend, type CryptoDegradationKind, type CryptoDegradedEvent, DeferredReply, type DownloadedMedia, type DurationOption, type EnumOption, type ExecutableCommandDefinition, type GroupAccess, type GroupAddressingMode, type GroupMetadataRecoveredEvent, type GroupParticipant, type GroupParticipantAction, type GroupParticipantsChanged, type GroupRole, type GroupSnapshot, type GuardResult, type HealthChangedEvent, type ImageContent, type InteractiveResponse, type InteractiveResponseKind, type InviteResult, type LinkButton, type ListContent, type ListRow, type ListSection, type LoadCommandsOptions, type LoadCommandsResult, type LoadedCommand, type LogContext, type LogEntry, type LogFormat, type LogLevel, type LogWriter, Logger, type LoggerConfig, type LoggerOptions, type LoginOptions, type MediaKind, type MediaSource, type MemberActionState, MemoryCache, type MemoryCacheStats, type MentionTarget, type Message, type MessageButton, type MessageContent, type MessageContentKind, type MessageDecodeFailureEvent, type MessageDeleted, type MessageDiscardReason, type MessageDiscardedEvent, type MessageEdited, type MessageKey, type MessageMedia, type MessagePayloadKind, type MessageProtocolKind, type MessageRecoveredEvent, type MessageRecoveryFailedEvent, type MessageUnavailableEvent, type MultiAccountOptions, type MultiAppEvent, type MultiAppHealth, MultiCommandRouter, type MultiLoadCommandsResult, type MultiLoginOptions, type MuteChangeResult, type MuteEnforcement, type MuteOptions, type MuteRecord, MuteService, type MuteStore, type NumberOption, ParsedCommandOptions, type ParticipantUpdateResult, type PollContent, type PresenceState, type ProviderConnectionHealth, type ProviderCryptoHealth, type ProviderGroupHealth, type ProviderHealth, type ProviderMessagingHealth, type ProviderStabilityEvent, type ProviderTimeoutHealth, type ProviderTimeoutOptions, type QuickReplyButton, type QuotedMessage, type ReconnectOptions, type RegisteredCommand, type RemoveMuteResult, type ReplyOptions, type RepostMessageOptions, type RouterOptions, type SentMessage, SqliteMuteStore, type StabilityHealthStatus, type StickerContent, type StoredMute, type StringOption, type TextContent, User, type UserData, type UserOption, type VideoContent, WhaNextApp, WhaNextError, type WhaNextErrorCode, WhaNextMultiApp, type WhatsAppProvider, create, createMulti, defineCommand, defineCommandGroup, defineCommands, defineSubcommand, guards, isCommandGroup, loadCommands, option, toWhaNextError };

package/dist/index.js

@@ -2346,7 +2346,18 @@ 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
     };
     const crypto = provider?.crypto ?? {
       backend: "unknown",
@@ -2467,6 +2478,16 @@ 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);
       }
       await this.#refreshHealthState();
     });
@@ -3141,6 +3162,8 @@ 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 +3174,8 @@ var ZapoProvider = class {
   #messageStore = /* @__PURE__ */ new Map();
   #messageKeyStore = /* @__PURE__ */ new WeakMap();
   #deliveredMessageStore = /* @__PURE__ */ new Set();
+  #pendingUnavailableRecoveries = /* @__PURE__ */ new Map();
+  #recentDecryptedPayloads = /* @__PURE__ */ new Map();
   #handledProtocolStore = /* @__PURE__ */ new Set();
   #callCreatorStore = /* @__PURE__ */ new Map();
   #groupMetadataRecoveryAt = /* @__PURE__ */ new Map();
@@ -3181,6 +3206,17 @@ 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;
   #lastIncomingAt;
   #lastOutgoingAt;
   #decryptFailures = 0;
@@ -3221,6 +3257,17 @@ 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,
         ...this.#lastIncomingAt ? { lastIncomingAt: new Date(this.#lastIncomingAt) } : {},
         ...this.#lastOutgoingAt ? { lastOutgoingAt: new Date(this.#lastOutgoingAt) } : {}
       },
@@ -3267,6 +3314,11 @@ var ZapoProvider = class {
       clearTimeout(this.#healthRefreshTimer);
       this.#healthRefreshTimer = void 0;
     }
+    for (const pending of this.#pendingUnavailableRecoveries.values()) {
+      clearTimeout(pending.timer);
+    }
+    this.#pendingUnavailableRecoveries.clear();
+    this.#recentDecryptedPayloads.clear();
     const client = this.#client;
     this.#connectPromise = void 0;
     try {
@@ -3628,6 +3680,15 @@ var ZapoProvider = class {
       }
       this.#handleMessage(event);
     });
+    client.on("message_unavailable", (event) => {
+      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;
@@ -3666,7 +3727,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(
+      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 +3744,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,7 +3754,15 @@ 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();
@@ -3696,6 +3775,162 @@ 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;
+    const correlationKey = this.#stanzaCorrelationKey(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 correlationKey = this.#stanzaCorrelationKey(event.chatJid, 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.#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.#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);
@@ -4433,11 +4668,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) {