@whanext/core 0.19.19 → 0.19.21

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.19.21
+
+### Added
+- `MessageService.edit()` accepts an optional protocol-level `id` override for the outgoing edit envelope.
+
+### Zapo
+- Forwards the optional edit `id` to `WaSendMessageOptions.id`, enabling specialized moderation workflows without exposing the provider client.
+
+## 0.19.20
+
+### Ingress diagnostics
+- Added opt-in provider ingress tracing with `providerDiagnostics.ingress`, correlating Zapo transport message stanzas through decrypt and terminal provider events without logging message content or decrypted bytes.
+- Added a bounded ingress watchdog through `providerDiagnostics.ingressStallTimeoutMs`, defaulting to 10 seconds. A decoded `<message>` stanza that never becomes `message`, `message_unavailable`, a decode failure, or a decrypt failure emits `messageIngressStalled` and temporarily marks the provider as degraded.
+- Added transport decode diagnostics from Zapo 1.8.0 `debug_transport_decode_error` with a typed `transportDecodeFailure` event. Only frame size and error metadata are exposed; raw frame bytes are never logged or emitted.
+- Expanded `health().messaging` with `transportFramesIn`, `transportNodesIn`, `transportDecodeErrors`, `messageStanzasIn`, and `ingressStalls`.
+- When ingress diagnostics are enabled, message stanzas log their stanza id, chat, participant, addressing mode, encryption types, decrypt stage, and terminal provider stage. Message text and plaintext payloads are never included.
+
+### Reliability
+- Correlates decrypt warnings with pending message stanzas so known Signal failures do not appear as generic ingress stalls.
+- Normalizes device-qualified PN/LID JIDs before ingress correlation, keeping group and direct-message diagnostics aligned with Zapo message keys.
+
 ## 0.19.19
 
 ### Provider

package/README.md

@@ -347,6 +347,19 @@ 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.
 
+Para diagnosticar mensagens que chegam ao socket mas não viram um `Message` público, ative a trilha de ingresso:
+
+```ts
+const app = await create({
+  providerDiagnostics: {
+    ingress: true,
+    ingressStallTimeoutMs: 10_000,
+  },
+});
+```
+
+Com essa opção, o provider registra apenas metadados seguros de stanzas `<message>` e correlaciona `debug_transport_node_in`, `debug_decrypted_payload`, `message`, `message_unavailable`, falhas de decrypt e falhas de decode. `health().messaging` também expõe `transportFramesIn`, `transportNodesIn`, `transportDecodeErrors`, `messageStanzasIn` e `ingressStalls`. Frames brutos, bytes descriptografados e texto das mensagens nunca são escritos nos logs.
+
 ```ts
 server.get('/health', async () => app.health());
 ```

package/dist/index.d.ts

@@ -163,6 +163,13 @@ type MentionTarget = string | User;
 interface RepostMessageOptions {
     mentions?: readonly MentionTarget[];
 }
+interface EditMessageOptions {
+    /**
+     * Overrides the stanza id used by the outgoing edit envelope.
+     * Advanced/protocol-level option; omitted for normal edits.
+     */
+    id?: string;
+}
 interface TextContent {
     text: string;
     mentions?: MentionTarget[];
@@ -326,6 +333,11 @@ interface ProviderMessagingHealth {
     ignoredOffline: number;
     duplicates: number;
     normalizationFailures: number;
+    transportFramesIn: number;
+    transportNodesIn: number;
+    transportDecodeErrors: number;
+    messageStanzasIn: number;
+    ingressStalls: number;
     lastIncomingAt?: Date;
     lastOutgoingAt?: Date;
 }
@@ -401,6 +413,23 @@ interface MessageDiscardedEvent {
     messageId?: string;
     chatId?: string;
 }
+type MessageIngressStage = 'stanza_received' | 'decrypted';
+interface MessageIngressStalledEvent {
+    occurredAt: Date;
+    waitedMs: number;
+    lastStage: MessageIngressStage;
+    stanzaId: string;
+    chatId?: string;
+    participantId?: string;
+    stanzaType?: string;
+    addressingMode?: string;
+}
+interface TransportDecodeFailureEvent {
+    occurredAt: Date;
+    frameBytes: number;
+    errorName: string;
+    errorMessage: string;
+}
 type ProviderStabilityEvent = {
     type: 'groupMetadataRecovered';
     payload: GroupMetadataRecoveredEvent;
@@ -422,6 +451,12 @@ type ProviderStabilityEvent = {
 } | {
     type: 'messageDiscarded';
     payload: MessageDiscardedEvent;
+} | {
+    type: 'messageIngressStalled';
+    payload: MessageIngressStalledEvent;
+} | {
+    type: 'transportDecodeFailure';
+    payload: TransportDecodeFailureEvent;
 } | {
     type: 'healthRefresh';
     payload: {
@@ -452,7 +487,7 @@ interface WhatsAppProvider {
     repostMessage(source: MessageKey, chatId: string, options?: RepostMessageOptions): Promise<SentMessage>;
     reactToMessage(key: MessageKey, emoji?: string): Promise<SentMessage>;
     downloadMedia(key: MessageKey): Promise<DownloadedMedia>;
-    editMessage(key: MessageKey, content: string): Promise<SentMessage>;
+    editMessage(key: MessageKey, content: string, options?: EditMessageOptions): Promise<SentMessage>;
     deleteMessage(key: MessageKey): Promise<void>;
     getGroup(groupId: string): Promise<GroupSnapshot>;
     setGroupAccess(groupId: string, access: GroupAccess): Promise<void>;
@@ -658,7 +693,7 @@ declare class MessageService {
      * media and structured WhatsApp messages as well as text.
      */
     repost(source: Message | MessageKey, chatId: string, options?: RepostMessageOptions): Promise<SentMessage>;
-    edit(message: Message | SentMessage | MessageKey, text: string): Promise<SentMessage>;
+    edit(message: Message | SentMessage | MessageKey, text: string, options?: EditMessageOptions): Promise<SentMessage>;
     delete(message: Message | SentMessage | MessageKey): Promise<void>;
     react(message: Message | SentMessage | MessageKey, emoji: string): Promise<SentMessage>;
     unreact(message: Message | SentMessage | MessageKey): Promise<SentMessage>;
@@ -1003,6 +1038,8 @@ interface AppEvents {
     messageRecoveryFailed: MessageRecoveryFailedEvent;
     messageDecodeFailure: MessageDecodeFailureEvent;
     messageDiscarded: MessageDiscardedEvent;
+    messageIngressStalled: MessageIngressStalledEvent;
+    transportDecodeFailure: TransportDecodeFailureEvent;
     commandQueueTimeout: CommandQueueTimeoutEvent;
     commandQueueFull: CommandQueueFullEvent;
 }
@@ -1068,6 +1105,10 @@ interface ProviderTimeoutOptions {
     connectTimeoutMs?: number;
     nodeQueryTimeoutMs?: number;
 }
+interface ProviderDiagnosticsOptions {
+    ingress?: boolean;
+    ingressStallTimeoutMs?: number;
+}
 interface ReconnectOptions {
     enabled?: boolean;
     maxAttempts?: number;
@@ -1085,6 +1126,7 @@ interface CreateOptions {
     router?: Omit<RouterOptions, 'prefix'>;
     reconnect?: ReconnectOptions;
     providerTimeouts?: ProviderTimeoutOptions;
+    providerDiagnostics?: ProviderDiagnosticsOptions;
     messageCacheSize?: number;
     processOfflineMessages?: boolean;
     provider?: WhatsAppProvider;
@@ -1172,4 +1214,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 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 };
+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 EditMessageOptions, 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 MessageIngressStage, type MessageIngressStalledEvent, 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 ProviderDiagnosticsOptions, 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, type TransportDecodeFailureEvent, 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

@@ -2239,9 +2239,9 @@ var MessageService = class {
     const key = "keys" in source ? source.keys : source;
     return this.#provider.repostMessage(key, chatId, options);
   }
-  edit(message, text) {
+  edit(message, text, options = {}) {
     const key = "keys" in message ? message.keys : message;
-    return this.#provider.editMessage(key, text);
+    return this.#provider.editMessage(key, text, options);
   }
   delete(message) {
     const key = "keys" in message ? message.keys : message;
@@ -2357,7 +2357,12 @@ var WhaNextApp = class {
       unhandledStanzas: 0,
       ignoredOffline: 0,
       duplicates: 0,
-      normalizationFailures: 0
+      normalizationFailures: 0,
+      transportFramesIn: 0,
+      transportNodesIn: 0,
+      transportDecodeErrors: 0,
+      messageStanzasIn: 0,
+      ingressStalls: 0
     };
     const crypto = provider?.crypto ?? {
       backend: "unknown",
@@ -2488,6 +2493,10 @@ var WhaNextApp = class {
         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();
     });
@@ -3157,6 +3166,7 @@ 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;
@@ -3176,6 +3186,7 @@ var ZapoProvider = class {
   #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();
@@ -3184,6 +3195,8 @@ var ZapoProvider = class {
   #cryptoBackend;
   #connectTimeoutMs;
   #nodeQueryTimeoutMs;
+  #ingressDiagnostics;
+  #ingressStallTimeoutMs;
   #protocolMutationQueue = Promise.resolve();
   #state = "idle";
   #client;
@@ -3217,6 +3230,11 @@ var ZapoProvider = class {
   #ignoredOfflineMessages = 0;
   #duplicateMessages = 0;
   #normalizationFailures = 0;
+  #transportFramesIn = 0;
+  #transportNodesIn = 0;
+  #transportDecodeErrors = 0;
+  #messageStanzasIn = 0;
+  #ingressStalls = 0;
   #lastIncomingAt;
   #lastOutgoingAt;
   #decryptFailures = 0;
@@ -3234,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) {
@@ -3268,6 +3288,11 @@ var ZapoProvider = class {
         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) } : {}
       },
@@ -3318,6 +3343,10 @@ var ZapoProvider = class {
       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;
@@ -3462,12 +3491,15 @@ var ZapoProvider = class {
       );
     }
   }
-  async editMessage(key, content) {
+  async editMessage(key, content, options = {}) {
     return this.#trackOutgoing(async () => {
       const result = await this.#requireClient().message.send(
         key.chatId,
         content,
-        { editKey: this.#toZapoKey(key) }
+        {
+          editKey: this.#toZapoKey(key),
+          ...options.id ? { id: options.id } : {}
+        }
       );
       return this.#sent(result, key.chatId);
     });
@@ -3657,7 +3689,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({
@@ -3681,6 +3728,7 @@ 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) => {
@@ -3720,6 +3768,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);
@@ -3730,7 +3911,7 @@ var ZapoProvider = class {
     const deliveryKey = this.#messageDeliveryKey(stored.key);
     this.#resolveUnavailableRecovery(deliveryKey, stored.key);
     const decryptedCorrelationKey = this.#stanzaCorrelationKey(
-      stored.key.remoteJid ?? void 0,
+      normalizeIngressJid(stored.key.remoteJid ?? void 0),
       stored.key.id ?? void 0
     );
     if (decryptedCorrelationKey) this.#recentDecryptedPayloads.delete(decryptedCorrelationKey);
@@ -3766,6 +3947,16 @@ var ZapoProvider = class {
     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(
@@ -3870,7 +4061,8 @@ var ZapoProvider = class {
   }
   #handleDecryptedPayload(event) {
     this.#decryptedPayloads += 1;
-    const correlationKey = this.#stanzaCorrelationKey(event.chatJid, event.stanzaId);
+    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, {
@@ -3885,11 +4077,13 @@ var ZapoProvider = class {
   }
   #handleUnhandledStanza(event) {
     this.#unhandledStanzas += 1;
-    const correlationKey = this.#stanzaCorrelationKey(event.chatJid, event.stanzaId);
+    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",
@@ -3910,6 +4104,7 @@ var ZapoProvider = class {
       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 } : {},
@@ -4188,6 +4383,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;
@@ -5353,6 +5553,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";
@@ -5453,7 +5660,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 } : {},
@@ -5691,6 +5900,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,