zapo-js 0.1.1 → 0.2.0

package/dist/esm/retry/index.js

@@ -1,5 +1,6 @@
 export { MAX_RETRY_ATTEMPTS, RETRY_KEYS_MIN_COUNT, RETRY_OUTBOUND_TTL_MS, RETRY_REASON, RETRY_RECEIPT_VERSION } from './constants.js';
 export { mapRetryReasonFromError } from './reason.js';
-export { parseRetryReceiptRequest } from './parse.js';
-export { decodeRetryReplayPayload, encodeRetryReplayPayload, pickRetryStateMax } from './outbound.js';
+export { parseRetryReceiptRequest, pickRetryStateMax } from './parse.js';
+export { decodeRetryReplayPayload, encodeRetryReplayPayload } from './codec.js';
 export { WaRetryReplayService } from './replay.js';
+export { createOutboundRetryTracker } from './tracker.js';

package/dist/esm/retry/parse.js

@@ -1,98 +1,95 @@
 import { WA_MESSAGE_TAGS, WA_NODE_TAGS } from '../protocol/constants.js';
+import { normalizeDeviceJid } from '../protocol/jid.js';
+import { decodeExactLength, parseUint } from '../signal/api/codec.js';
 import { SIGNAL_KEY_DATA_LENGTH, SIGNAL_KEY_ID_LENGTH, SIGNAL_REGISTRATION_ID_LENGTH, SIGNAL_SIGNATURE_LENGTH } from '../signal/api/constants.js';
-import { decodeNodeContentBase64OrBytes, findNodeChild } from '../transport/node/helpers.js';
-import { parseOptionalInt } from '../transport/stream/parse.js';
-function parseFixedLengthBytes(value, byteLength, field) {
-    const out = decodeNodeContentBase64OrBytes(value, field);
-    if (out.byteLength !== byteLength) {
-        throw new Error(`${field} must be ${byteLength} bytes`);
-    }
-    return out;
-}
-function parseBigEndianUint(bytes, field) {
-    if (bytes.byteLength === 0 || bytes.byteLength > 4) {
-        throw new Error(`${field} has invalid byte length`);
-    }
-    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-    if (bytes.byteLength === 1) {
-        return view.getUint8(0);
-    }
-    if (bytes.byteLength === 2) {
-        return view.getUint16(0);
-    }
-    return bytes.byteLength === 3 ? (view.getUint16(0) << 8) | view.getUint8(2) : view.getUint32(0);
-}
-function parseRetryType(value) {
-    if (value === 'retry' || value === 'enc_rekey_retry') {
-        return value;
-    }
-    return null;
-}
-function parseRetryCount(value) {
-    const parsed = parseOptionalInt(value);
-    if (parsed === undefined) {
-        return 0;
-    }
-    if (parsed < 0) {
-        throw new Error('retry count must be >= 0');
+import { decodeNodeContentBase64OrBytes, findNodeChildrenByTags } from '../transport/node/helpers.js';
+import { parseOptionalInt } from '../util/primitives.js';
+const RETRY_STATE_RANK = {
+    pending: 0,
+    delivered: 1,
+    read: 2,
+    played: 3,
+    ineligible: 4
+};
+function requireNode(node, message) {
+    if (!node) {
+        throw new Error(message);
     }
-    return parsed;
+    return node;
 }
-function parseRetryReason(value) {
-    const parsed = parseOptionalInt(value);
-    if (parsed === undefined) {
-        return undefined;
-    }
-    if (parsed < 0) {
-        throw new Error('retry reason must be >= 0');
+function validateRetryReceiptToAttr(to, expectedToJids) {
+    if (!to || !expectedToJids || expectedToJids.length === 0) {
+        return;
+    }
+    let normalizedTo;
+    try {
+        normalizedTo = normalizeDeviceJid(to);
+    }
+    catch {
+        throw new Error('retry receipt has invalid to attr');
+    }
+    for (let index = 0; index < expectedToJids.length; index += 1) {
+        const expected = expectedToJids[index]?.trim();
+        if (!expected)
+            continue;
+        try {
+            if (normalizeDeviceJid(expected) === normalizedTo) {
+                return;
+            }
+        }
+        catch {
+            continue;
+        }
     }
-    return parsed;
+    throw new Error('retry receipt to attr does not match local device');
 }
 function parseRetryKeyBundle(node) {
     if (!node) {
         return undefined;
     }
-    const identityNode = findNodeChild(node, WA_NODE_TAGS.IDENTITY);
-    const signedKeyNode = findNodeChild(node, WA_NODE_TAGS.SKEY);
-    if (!identityNode || !signedKeyNode) {
-        throw new Error('retry keys section missing identity or skey');
-    }
-    const signedKeyIdNode = findNodeChild(signedKeyNode, WA_NODE_TAGS.ID);
-    const signedKeyValueNode = findNodeChild(signedKeyNode, WA_NODE_TAGS.VALUE);
-    const signedKeySignatureNode = findNodeChild(signedKeyNode, WA_NODE_TAGS.SIGNATURE);
-    if (!signedKeyIdNode || !signedKeyValueNode || !signedKeySignatureNode) {
-        throw new Error('retry keys section has incomplete skey');
-    }
-    const keyNode = findNodeChild(node, WA_NODE_TAGS.KEY);
-    const keyIdNode = keyNode ? findNodeChild(keyNode, WA_NODE_TAGS.ID) : undefined;
-    const keyValueNode = keyNode ? findNodeChild(keyNode, WA_NODE_TAGS.VALUE) : undefined;
-    if (keyNode && (!keyIdNode || !keyValueNode)) {
-        throw new Error('retry keys section has incomplete key');
-    }
-    const deviceIdentityNode = findNodeChild(node, WA_NODE_TAGS.DEVICE_IDENTITY);
+    const [identityNode, signedKeyNode, keyNode, deviceIdentityNode] = findNodeChildrenByTags(node, [WA_NODE_TAGS.IDENTITY, WA_NODE_TAGS.SKEY, WA_NODE_TAGS.KEY, WA_NODE_TAGS.DEVICE_IDENTITY]);
+    const identity = requireNode(identityNode, 'retry keys section missing identity or skey');
+    const signedKey = requireNode(signedKeyNode, 'retry keys section missing identity or skey');
+    const [signedKeyIdNode, signedKeyValueNode, signedKeySignatureNode] = findNodeChildrenByTags(signedKey, [WA_NODE_TAGS.ID, WA_NODE_TAGS.VALUE, WA_NODE_TAGS.SIGNATURE]);
+    const signedKeyId = requireNode(signedKeyIdNode, 'retry keys section has incomplete skey');
+    const signedKeyValue = requireNode(signedKeyValueNode, 'retry keys section has incomplete skey');
+    const signedKeySignature = requireNode(signedKeySignatureNode, 'retry keys section has incomplete skey');
+    let keyIdNode;
+    let keyValueNode;
+    if (keyNode) {
+        const keyNodes = findNodeChildrenByTags(keyNode, [WA_NODE_TAGS.ID, WA_NODE_TAGS.VALUE]);
+        keyIdNode = keyNodes[0];
+        keyValueNode = keyNodes[1];
+    }
+    const keyId = keyNode ? requireNode(keyIdNode, 'retry keys section has incomplete key') : null;
+    const keyValue = keyNode
+        ? requireNode(keyValueNode, 'retry keys section has incomplete key')
+        : null;
     return {
-        identity: parseFixedLengthBytes(identityNode.content, SIGNAL_KEY_DATA_LENGTH, 'retry.keys.identity'),
+        identity: decodeExactLength(identity.content, 'retry.keys.identity', SIGNAL_KEY_DATA_LENGTH),
         deviceIdentity: deviceIdentityNode
             ? decodeNodeContentBase64OrBytes(deviceIdentityNode.content, 'retry.keys.device-identity')
             : undefined,
-        key: keyIdNode && keyValueNode
+        key: keyId && keyValue
             ? {
-                id: parseBigEndianUint(parseFixedLengthBytes(keyIdNode.content, SIGNAL_KEY_ID_LENGTH, 'retry.keys.key.id'), 'retry.keys.key.id'),
-                publicKey: parseFixedLengthBytes(keyValueNode.content, SIGNAL_KEY_DATA_LENGTH, 'retry.keys.key.value')
+                id: parseUint(decodeExactLength(keyId.content, 'retry.keys.key.id', SIGNAL_KEY_ID_LENGTH), 'retry.keys.key.id'),
+                publicKey: decodeExactLength(keyValue.content, 'retry.keys.key.value', SIGNAL_KEY_DATA_LENGTH)
             }
             : undefined,
         skey: {
-            id: parseBigEndianUint(parseFixedLengthBytes(signedKeyIdNode.content, SIGNAL_KEY_ID_LENGTH, 'retry.keys.skey.id'), 'retry.keys.skey.id'),
-            publicKey: parseFixedLengthBytes(signedKeyValueNode.content, SIGNAL_KEY_DATA_LENGTH, 'retry.keys.skey.value'),
-            signature: parseFixedLengthBytes(signedKeySignatureNode.content, SIGNAL_SIGNATURE_LENGTH, 'retry.keys.skey.signature')
+            id: parseUint(decodeExactLength(signedKeyId.content, 'retry.keys.skey.id', SIGNAL_KEY_ID_LENGTH), 'retry.keys.skey.id'),
+            publicKey: decodeExactLength(signedKeyValue.content, 'retry.keys.skey.value', SIGNAL_KEY_DATA_LENGTH),
+            signature: decodeExactLength(signedKeySignature.content, 'retry.keys.skey.signature', SIGNAL_SIGNATURE_LENGTH)
         }
     };
 }
-export function parseRetryReceiptRequest(node) {
+export function parseRetryReceiptRequest(node, options) {
     if (node.tag !== WA_MESSAGE_TAGS.RECEIPT) {
         return null;
     }
-    const receiptType = parseRetryType(node.attrs.type);
+    const receiptType = node.attrs.type === 'retry' || node.attrs.type === 'enc_rekey_retry'
+        ? node.attrs.type
+        : null;
     if (!receiptType) {
         return null;
     }
@@ -101,30 +98,35 @@ export function parseRetryReceiptRequest(node) {
     if (!stanzaId || !from) {
         throw new Error('retry receipt is missing id/from attrs');
     }
-    const retryNode = findNodeChild(node, 'retry');
-    if (!retryNode) {
-        throw new Error('retry receipt is missing retry child');
-    }
-    const registrationNode = findNodeChild(node, WA_NODE_TAGS.REGISTRATION);
-    if (!registrationNode) {
-        throw new Error('retry receipt is missing registration child');
-    }
-    const originalMsgId = retryNode.attrs.id;
+    validateRetryReceiptToAttr(node.attrs.to, options?.expectedToJids);
+    const [retryNode, registrationNode, keysNode] = findNodeChildrenByTags(node, [
+        'retry',
+        WA_NODE_TAGS.REGISTRATION,
+        'keys'
+    ]);
+    const retry = requireNode(retryNode, 'retry receipt is missing retry child');
+    const registrationNodeValue = requireNode(registrationNode, 'retry receipt is missing registration child');
+    const originalMsgId = retry.attrs.id;
     if (!originalMsgId) {
         throw new Error('retry receipt is missing retry.id');
     }
-    const registration = parseFixedLengthBytes(registrationNode.content, SIGNAL_REGISTRATION_ID_LENGTH, 'retry.registration');
+    const registration = decodeExactLength(registrationNodeValue.content, 'retry.registration', SIGNAL_REGISTRATION_ID_LENGTH);
     return {
         type: receiptType,
         stanzaId,
         from,
         participant: node.attrs.participant,
         recipient: node.attrs.recipient,
+        offline: node.attrs.offline !== undefined,
+        isLid: node.attrs.is_lid === 'true',
         originalMsgId,
-        retryCount: parseRetryCount(retryNode.attrs.count),
-        retryReason: parseRetryReason(retryNode.attrs.error ?? node.attrs.error),
-        t: retryNode.attrs.t ?? node.attrs.t,
-        regId: parseBigEndianUint(registration, 'retry.registration'),
-        keyBundle: parseRetryKeyBundle(findNodeChild(node, 'keys'))
+        retryCount: parseOptionalInt(retry.attrs.count) ?? 0,
+        retryReason: parseOptionalInt(retry.attrs.error ?? node.attrs.error),
+        t: retry.attrs.t ?? node.attrs.t,
+        regId: parseUint(registration, 'retry.registration'),
+        keyBundle: parseRetryKeyBundle(keysNode)
     };
 }
+export function pickRetryStateMax(left, right) {
+    return RETRY_STATE_RANK[left] >= RETRY_STATE_RANK[right] ? left : right;
+}

package/dist/esm/retry/replay.js

@@ -1,29 +1,34 @@
 import { wrapDeviceSentMessage } from '../message/device-sent.js';
 import { unpadPkcs7, writeRandomPadMax16 } from '../message/padding.js';
 import { proto } from '../proto.js';
-import { isGroupOrBroadcastJid, normalizeDeviceJid, parseSignalAddressFromJid, splitJid, toUserJid } from '../protocol/jid.js';
-import { decodeRetryReplayPayload } from './outbound.js';
+import { isGroupOrBroadcastJid, normalizeDeviceJid, parseJidFull, toUserJid } from '../protocol/jid.js';
+import { decodeRetryReplayPayload } from './codec.js';
 import { decodeBinaryNode } from '../transport/binary/index.js';
 import { buildGroupRetryMessageNode } from '../transport/node/builders/message.js';
-import { findNodeChild, getNodeChildrenByTag } from '../transport/node/helpers.js';
+import { findNodeChild } from '../transport/node/helpers.js';
 import { toError } from '../util/primitives.js';
 export class WaRetryReplayService {
     constructor(options) {
         this.options = options;
     }
     async resendOutboundMessage(outbound, requesterJid, retryCount) {
-        const payload = decodeRetryReplayPayload(outbound.replayPayload);
+        const payload = outbound.replayPayload instanceof Uint8Array
+            ? decodeRetryReplayPayload(outbound.replayPayload)
+            : outbound.replayPayload;
+        const requesterParsed = parseJidFull(requesterJid);
+        const requesterAddress = requesterParsed.address;
+        const normalizedRequesterJid = requesterParsed.normalizedJid;
         if (payload.mode === 'plaintext') {
-            return this.resendPlaintextPayload(outbound, payload, requesterJid, retryCount);
+            return this.resendPlaintextPayload(outbound, payload, requesterJid, requesterAddress, retryCount);
         }
         if (payload.mode === 'encrypted') {
-            return this.resendEncryptedPayload(outbound, payload, requesterJid, retryCount);
+            return this.resendEncryptedPayload(outbound, payload, requesterJid, normalizedRequesterJid, retryCount);
         }
-        return this.resendOpaquePayload(outbound, payload, requesterJid);
+        return this.resendOpaquePayload(outbound, payload, normalizedRequesterJid);
     }
-    async resendPlaintextPayload(outbound, payload, requesterJid, retryCount) {
+    async resendPlaintextPayload(outbound, payload, requesterJid, requesterAddress, retryCount) {
         if (isGroupOrBroadcastJid(payload.to)) {
-            return this.resendGroupPlaintextPayload(outbound, payload, requesterJid);
+            return this.resendGroupPlaintextPayload(outbound, payload, requesterJid, requesterAddress, retryCount);
         }
         let payloadUserJid;
         let requesterUserJid;
@@ -37,8 +42,8 @@ export class WaRetryReplayService {
         if (payloadUserJid !== requesterUserJid) {
             return 'ineligible';
         }
-        const encrypted = await this.signalProtocol.encryptMessage(parseSignalAddressFromJid(requesterJid), payload.plaintext);
-        await this.messageClient.sendEncrypted({
+        const encrypted = await this.options.signalProtocol.encryptMessage(requesterAddress, payload.plaintext);
+        await this.options.messageClient.sendEncrypted({
             to: requesterJid,
             encType: encrypted.type,
             ciphertext: encrypted.ciphertext,
@@ -48,15 +53,15 @@ export class WaRetryReplayService {
         });
         return 'resent';
     }
-    async resendGroupPlaintextPayload(outbound, payload, requesterJid) {
+    async resendGroupPlaintextPayload(outbound, payload, requesterJid, requesterAddress, retryCount) {
         const plaintext = (await this.maybeWrapGroupRetryPlaintextForSelfDevice(payload, requesterJid)) ??
             payload.plaintext;
-        const encrypted = await this.signalProtocol.encryptMessage(parseSignalAddressFromJid(requesterJid), plaintext);
+        const encrypted = await this.options.signalProtocol.encryptMessage(requesterAddress, plaintext);
         let deviceIdentity;
         if (encrypted.type === 'pkmsg') {
-            const signedIdentity = this.getCurrentSignedIdentity();
+            const signedIdentity = this.options.getCurrentSignedIdentity();
             if (!signedIdentity) {
-                this.logger.warn('retry request rejected: missing signed identity for pkmsg group retry');
+                this.options.logger.warn('retry request rejected: missing signed identity for pkmsg group retry');
                 return 'ineligible';
             }
             deviceIdentity = proto.ADVSignedDeviceIdentity.encode(signedIdentity).finish();
@@ -66,22 +71,23 @@ export class WaRetryReplayService {
             type: payload.type,
             id: outbound.messageId,
             requesterJid,
-            addressingMode: splitJid(requesterJid).server === 'lid' ? 'lid' : 'pn',
+            addressingMode: requesterAddress.server === 'lid' ? 'lid' : 'pn',
             encType: encrypted.type,
             ciphertext: encrypted.ciphertext,
+            retryCount,
             deviceIdentity
         });
-        await this.messageClient.sendMessageNode(retryNode);
+        await this.options.messageClient.sendMessageNode(retryNode);
         return 'resent';
     }
-    async resendEncryptedPayload(outbound, payload, requesterJid, retryCount) {
+    async resendEncryptedPayload(outbound, payload, requesterJid, normalizedRequesterJid, retryCount) {
         if (payload.encType === 'skmsg') {
             return 'ineligible';
         }
-        if (normalizeDeviceJid(payload.to) !== normalizeDeviceJid(requesterJid)) {
+        if (normalizeDeviceJid(payload.to) !== normalizedRequesterJid) {
             return 'ineligible';
         }
-        await this.messageClient.sendEncrypted({
+        await this.options.messageClient.sendEncrypted({
             to: requesterJid,
             encType: payload.encType,
             ciphertext: payload.ciphertext,
@@ -92,8 +98,11 @@ export class WaRetryReplayService {
         });
         return 'resent';
     }
-    async resendOpaquePayload(outbound, payload, requesterJid) {
+    async resendOpaquePayload(outbound, payload, normalizedRequesterJid) {
         const decoded = decodeBinaryNode(payload.node);
+        if (!this.isOpaqueReplayCompatible(decoded, normalizedRequesterJid)) {
+            return 'ineligible';
+        }
         const replayNode = decoded.attrs.id === outbound.messageId
             ? decoded
             : {
@@ -103,10 +112,7 @@ export class WaRetryReplayService {
                     id: outbound.messageId
                 }
             };
-        if (!this.isOpaqueReplayCompatible(replayNode, requesterJid)) {
-            return 'ineligible';
-        }
-        await this.messageClient.sendMessageNode(replayNode);
+        await this.options.messageClient.sendMessageNode(replayNode);
         return 'resent';
     }
     async maybeWrapGroupRetryPlaintextForSelfDevice(payload, requesterJid) {
@@ -120,7 +126,7 @@ export class WaRetryReplayService {
             return writeRandomPadMax16(proto.Message.encode(wrapped).finish());
         }
         catch (error) {
-            this.logger.warn('retry request failed to wrap deviceSent payload for self requester', {
+            this.options.logger.warn('retry request failed to wrap deviceSent payload for self requester', {
                 requester: requesterJid,
                 to: payload.to,
                 message: toError(error).message
@@ -140,38 +146,35 @@ export class WaRetryReplayService {
         }
         return false;
     }
-    get logger() {
-        return this.options.logger;
-    }
-    get messageClient() {
-        return this.options.messageClient;
-    }
-    get signalProtocol() {
-        return this.options.signalProtocol;
-    }
-    getCurrentSignedIdentity() {
-        return this.options.getCurrentSignedIdentity();
-    }
-    isOpaqueReplayCompatible(node, requesterJid) {
-        const requester = normalizeDeviceJid(requesterJid);
+    isOpaqueReplayCompatible(node, normalizedRequesterJid) {
         const participantsNode = findNodeChild(node, 'participants');
         if (participantsNode) {
-            const toNodes = getNodeChildrenByTag(participantsNode, 'to');
-            if (toNodes.length !== 1) {
-                return false;
+            const participantsContent = Array.isArray(participantsNode.content)
+                ? participantsNode.content
+                : [];
+            let participantNode;
+            let participantCount = 0;
+            for (let index = 0; index < participantsContent.length; index++) {
+                const child = participantsContent[index];
+                if (child.tag !== 'to')
+                    continue;
+                participantCount++;
+                if (participantCount > 1)
+                    return false;
+                participantNode = child;
             }
-            const participantJid = toNodes[0].attrs.jid;
-            if (!participantJid) {
+            if (participantCount !== 1 || !participantNode)
                 return false;
-            }
-            return normalizeDeviceJid(participantJid) === requester;
+            const participantJid = participantNode.attrs.jid;
+            if (!participantJid)
+                return false;
+            return normalizeDeviceJid(participantJid) === normalizedRequesterJid;
         }
         if (node.attrs.participant) {
-            return normalizeDeviceJid(node.attrs.participant) === requester;
-        }
-        if (node.attrs.to) {
-            return normalizeDeviceJid(node.attrs.to) === requester;
+            return normalizeDeviceJid(node.attrs.participant) === normalizedRequesterJid;
         }
+        if (node.attrs.to)
+            return normalizeDeviceJid(node.attrs.to) === normalizedRequesterJid;
         return false;
     }
 }

package/dist/esm/retry/tracker.js

@@ -0,0 +1,94 @@
+import { isGroupOrBroadcastJid, normalizeDeviceJid } from '../protocol/jid.js';
+import { encodeRetryReplayPayload } from './codec.js';
+import { RETRY_OUTBOUND_TTL_MS } from './constants.js';
+import { toError } from '../util/primitives.js';
+export function createOutboundRetryTracker(options) {
+    const { retryStore, logger } = options;
+    const retryTtlMs = retryStore.getTtlMs?.() ?? RETRY_OUTBOUND_TTL_MS;
+    const supportsRawReplayPayload = retryStore.supportsRawReplayPayload?.() ?? false;
+    const normalizeEligibleRequesterDeviceJids = (values) => {
+        if (!values || values.length === 0) {
+            return undefined;
+        }
+        const deduped = new Set();
+        for (let index = 0; index < values.length; index += 1) {
+            const raw = values[index]?.trim();
+            if (!raw) {
+                continue;
+            }
+            try {
+                deduped.add(normalizeDeviceJid(raw));
+            }
+            catch {
+                continue;
+            }
+        }
+        if (deduped.size === 0) {
+            return undefined;
+        }
+        return Array.from(deduped);
+    };
+    const safeUpsertRetryOutboundRecord = async (record) => {
+        try {
+            await retryStore.upsertOutboundMessage(record);
+        }
+        catch (error) {
+            logger.warn('failed to persist retry outbound message record', {
+                messageId: record.messageId,
+                to: record.toJid,
+                mode: record.replayMode,
+                message: toError(error).message
+            });
+            return false;
+        }
+        return true;
+    };
+    return {
+        track: async (hint, publish) => {
+            const nowMs = Date.now();
+            const replayMode = hint.replayPayload.mode;
+            const resolvedToJid = hint.toJid ?? (replayMode === 'opaque_node' ? '' : hint.replayPayload.to);
+            const replayPayload = supportsRawReplayPayload
+                ? hint.replayPayload
+                : encodeRetryReplayPayload(hint.replayPayload);
+            let eligibleRequesterDeviceJids = normalizeEligibleRequesterDeviceJids(hint.eligibleRequesterDeviceJids);
+            if (!eligibleRequesterDeviceJids &&
+                resolvedToJid &&
+                !isGroupOrBroadcastJid(resolvedToJid)) {
+                try {
+                    eligibleRequesterDeviceJids = [normalizeDeviceJid(resolvedToJid)];
+                }
+                catch {
+                    eligibleRequesterDeviceJids = undefined;
+                }
+            }
+            const createRetryOutboundRecord = (messageId, updatedAtMs, expiresAtMs) => ({
+                messageId,
+                toJid: resolvedToJid,
+                participantJid: hint.participantJid,
+                recipientJid: hint.recipientJid,
+                eligibleRequesterDeviceJids,
+                deliveredRequesterDeviceJids: [],
+                messageType: hint.type,
+                replayMode,
+                replayPayload,
+                state: 'pending',
+                createdAtMs: nowMs,
+                updatedAtMs,
+                expiresAtMs
+            });
+            const result = await publish();
+            const persistedMessageId = result.id.trim();
+            if (!persistedMessageId) {
+                logger.warn('retry outbound record skipped: publish returned empty message id', {
+                    to: resolvedToJid,
+                    mode: replayMode
+                });
+                return result;
+            }
+            const persistedNowMs = Date.now();
+            await safeUpsertRetryOutboundRecord(createRetryOutboundRecord(persistedMessageId, persistedNowMs, persistedNowMs + retryTtlMs));
+            return result;
+        }
+    };
+}