zapo-js 0.3.0 → 1.0.0

package/dist/types/protocol/jid.d.ts

@@ -1,37 +1,115 @@
 import type { SignalAddress } from '../signal/types';
+/**
+ * Splits a JID into `user` and `server` parts at the `@` separator.
+ * Throws if the input does not contain a valid `user@server` shape.
+ */
 export declare function splitJid(jid: string): {
     readonly user: string;
     readonly server: string;
 };
+/**
+ * Normalizes a user-supplied recipient (phone number, group id, or full JID)
+ * into a canonical JID. Strings already containing `@` are returned as-is;
+ * dashed inputs map to `<input>@g.us` (group); pure-digit inputs map to
+ * `<digits>@s.whatsapp.net`.
+ */
 export declare function normalizeRecipientJid(to: string): string;
+/** Returns `true` for JIDs in the `@lid` server (linked-device identity). */
 export declare function isLidJid(jid: string): boolean;
+/** Returns `true` for JIDs in the `@s.whatsapp.net` server (phone-number user JIDs). */
+export declare function isUserJid(jid: string): boolean;
+/** Returns `true` for JIDs in the `@bot` server. */
+export declare function isBotJid(jid: string): boolean;
+/** Returns `true` for JIDs in the `@g.us` server (groups). */
 export declare function isGroupJid(jid: string): boolean;
+/** Returns `true` for JIDs in the `@broadcast` server (broadcast lists). */
 export declare function isBroadcastJid(jid: string): boolean;
+/** Returns `true` for the special `status@broadcast` JID. */
+export declare function isStatusBroadcastJid(jid: string): boolean;
+/** Returns `true` for JIDs in the `@newsletter` server. */
+export declare function isNewsletterJid(jid: string): boolean;
+/** Returns `true` for any group or broadcast JID. */
 export declare function isGroupOrBroadcastJid(jid: string): boolean;
 export interface ParsedJid {
     readonly address: SignalAddress;
     readonly userJid: string;
     readonly normalizedJid: string;
 }
+/**
+ * Parses a JID into a Signal-style `{ user, server, device }` address.
+ * `device` is `0` when the JID has no `:device` segment.
+ */
 export declare function parseSignalAddressFromJid(jid: string): SignalAddress;
+/**
+ * Parses a JID and returns the Signal address plus the user-only and
+ * fully-normalized device JID forms in a single pass.
+ */
 export declare function parseJidFull(jid: string): ParsedJid;
+/**
+ * Maps the hosted-account server variants (`hosted` / `hosted.lid`) back to
+ * their canonical Signal server (`hostDomain` / `lid`). Other servers are
+ * returned unchanged.
+ */
 export declare function canonicalizeSignalServer(server: string, hostDomain?: string): string;
+/**
+ * Returns the JID rewritten with its server canonicalized via
+ * {@link canonicalizeSignalServer} – used to derive the address Signal
+ * sessions are keyed by.
+ */
 export declare function canonicalizeSignalJid(jid: string, hostDomain?: string): string;
+/**
+ * Strips the `:device` segment from a JID, returning the bare `user@server`
+ * form. Set `options.canonicalizeSignalServer` to also rewrite hosted servers
+ * via {@link canonicalizeSignalServer}.
+ */
 export declare function toUserJid(jid: string, options?: {
     readonly canonicalizeSignalServer?: boolean;
     readonly hostDomain?: string;
 }): string;
+/**
+ * Returns the JID in its full device form. JIDs with `device === 0` lose the
+ * device segment (`user@server`); all others keep `user:device@server`.
+ */
 export declare function normalizeDeviceJid(jid: string): string;
+/**
+ * Appends `:device` to a bare user JID. A falsy `device` returns the input
+ * unchanged.
+ */
+export declare function applyDeviceToJid(userJid: string, device: number | undefined): string;
+/** Returns `true` when `deviceId` matches the WhatsApp hosted-device id. */
 export declare function isHostedDeviceId(deviceId: number): boolean;
+/** Returns `true` for the hosted server variants (`hosted` and `hosted.lid`). */
 export declare function isHostedServer(server: string): boolean;
+/**
+ * Returns `true` when the JID refers to a hosted device – either by server
+ * (`@hosted` / `@hosted.lid`) or by a `:HOSTED_DEVICE_ID@…` device segment.
+ */
 export declare function isHostedDeviceJid(jid: string): boolean;
+/**
+ * Builds a device JID from its parts. When `options.isHosted` is set, the
+ * hosted-server variant is selected (preserving LID vs phone) and the canonical
+ * hosted device id is used.
+ */
 export declare function buildDeviceJid(user: string, normalizedServer: string, deviceId: number, options?: {
     readonly rawServer?: string;
     readonly isHosted?: boolean;
 }): string;
+/**
+ * Extracts the numeric username and device id from the authenticated user's
+ * own JID. Throws when either segment is missing, non-numeric, or out of the
+ * safe-integer range.
+ */
 export declare function getLoginIdentity(meJid: string): {
     readonly username: number;
     readonly device: number;
 };
+/**
+ * Builds a `<digits>@s.whatsapp.net` JID from a free-form phone number,
+ * stripping non-digit characters. Throws when no digits are found.
+ */
 export declare function parsePhoneJid(input: string): string;
+/**
+ * Returns a stable `user|server|device` key for a Signal address, suitable
+ * as a Map/Set key.
+ */
 export declare function signalAddressKey(address: SignalAddress): string;

package/dist/types/protocol/media.d.ts

@@ -1,15 +1,23 @@
 export declare const WA_MEDIA_HKDF_INFO: Readonly<{
-    readonly document: "WhatsApp Document Keys";
-    readonly image: "WhatsApp Image Keys";
-    readonly sticker: "WhatsApp Image Keys";
-    readonly 'xma-image': "WhatsApp Image Keys";
-    readonly video: "WhatsApp Video Keys";
-    readonly gif: "WhatsApp Video Keys";
-    readonly audio: "WhatsApp Audio Keys";
-    readonly ptt: "WhatsApp Audio Keys";
-    readonly 'md-app-state': "WhatsApp App State Keys";
-    readonly 'md-msg-hist': "WhatsApp History Keys";
-    readonly history: "WhatsApp History Keys";
+    readonly document: NodeJS.NonSharedUint8Array;
+    readonly image: NodeJS.NonSharedUint8Array;
+    readonly sticker: NodeJS.NonSharedUint8Array;
+    readonly 'xma-image': NodeJS.NonSharedUint8Array;
+    readonly video: NodeJS.NonSharedUint8Array;
+    readonly gif: NodeJS.NonSharedUint8Array;
+    readonly audio: NodeJS.NonSharedUint8Array;
+    readonly ptt: NodeJS.NonSharedUint8Array;
+    readonly 'md-app-state': NodeJS.NonSharedUint8Array;
+    readonly 'md-msg-hist': NodeJS.NonSharedUint8Array;
+    readonly history: NodeJS.NonSharedUint8Array;
+    readonly 'sticker-pack': NodeJS.NonSharedUint8Array;
+    readonly 'thumbnail-sticker-pack': NodeJS.NonSharedUint8Array;
+    readonly 'thumbnail-link': NodeJS.NonSharedUint8Array;
 }>;
-export declare const WA_PREVIEW_MEDIA_HKDF_INFO = "Messenger Preview Keys";
-export declare function getWaMediaHkdfInfo(mediaType: string): string;
+export declare const WA_PREVIEW_MEDIA_HKDF_INFO: NodeJS.NonSharedUint8Array;
+/**
+ * Returns the HKDF `info` bytes used to derive per-media keys for a given
+ * media type. Throws for unsupported types – see {@link WA_MEDIA_HKDF_INFO}
+ * for the supported set.
+ */
+export declare function getWaMediaHkdfInfo(mediaType: string): Uint8Array;

package/dist/types/protocol/message.d.ts

@@ -11,6 +11,7 @@ export declare const WA_MESSAGE_TYPES: Readonly<{
     readonly ACK_TYPE_ERROR: "error";
     readonly ACK_CLASS_ERROR: "error";
     readonly ACK_CLASS_MESSAGE: "message";
+    readonly ACK_CLASS_CALL: "call";
     readonly RECEIPT_TYPE_DELIVERY: "delivery";
     readonly RECEIPT_TYPE_SENDER: "sender";
     readonly RECEIPT_TYPE_INACTIVE: "inactive";
@@ -22,7 +23,9 @@ export declare const WA_MESSAGE_TYPES: Readonly<{
     readonly RECEIPT_TYPE_PEER: "peer_msg";
     readonly RECEIPT_TYPE_SERVER_ERROR: "server-error";
     readonly RECEIPT_TYPE_RETRY: "retry";
+    readonly RECEIPT_TYPE_ENC_REKEY_RETRY: "enc_rekey_retry";
 }>;
+export type WaOutboundReceiptType = typeof WA_MESSAGE_TYPES.RECEIPT_TYPE_READ | typeof WA_MESSAGE_TYPES.RECEIPT_TYPE_READ_SELF | typeof WA_MESSAGE_TYPES.RECEIPT_TYPE_PLAYED | typeof WA_MESSAGE_TYPES.RECEIPT_TYPE_PLAYED_SELF | typeof WA_MESSAGE_TYPES.RECEIPT_TYPE_INACTIVE | typeof WA_MESSAGE_TYPES.RECEIPT_TYPE_HISTORY_SYNC;
 export declare const WA_RETRYABLE_ACK_CODES: readonly ["408", "429", "500", "503"];
 export declare const WA_STANZA_MSG_TYPES: Readonly<{
     readonly TEXT: "text";
@@ -36,6 +39,7 @@ export declare const WA_STANZA_MSG_TYPES: Readonly<{
 export declare const WA_EDIT_ATTRS: Readonly<{
     readonly MESSAGE_EDIT: "1";
     readonly PIN_IN_CHAT: "2";
+    readonly NEWSLETTER_EDIT: "3";
     readonly SENDER_REVOKE: "7";
     readonly ADMIN_REVOKE: "8";
 }>;

package/dist/types/protocol/newsletter.d.ts

@@ -0,0 +1,65 @@
+export declare const WA_NEWSLETTER_ROLES: Readonly<{
+    readonly SUBSCRIBER: "SUBSCRIBER";
+    readonly GUEST: "GUEST";
+    readonly ADMIN: "ADMIN";
+    readonly OWNER: "OWNER";
+}>;
+export type WaNewsletterRole = (typeof WA_NEWSLETTER_ROLES)[keyof typeof WA_NEWSLETTER_ROLES];
+export declare const WA_NEWSLETTER_STATE_TYPES: Readonly<{
+    readonly ACTIVE: "ACTIVE";
+    readonly SUSPENDED: "SUSPENDED";
+    readonly GEOSUSPENDED: "GEOSUSPENDED";
+    readonly DELETED: "DELETED";
+    readonly NON_EXISTING: "NON_EXISTING";
+}>;
+export type WaNewsletterStateType = (typeof WA_NEWSLETTER_STATE_TYPES)[keyof typeof WA_NEWSLETTER_STATE_TYPES];
+export declare const WA_NEWSLETTER_PICTURE_TYPES: Readonly<{
+    readonly IMAGE: "IMAGE";
+    readonly PREVIEW: "PREVIEW";
+}>;
+export declare const WA_NEWSLETTER_FETCH_KEY_TYPES: Readonly<{
+    readonly JID: "JID";
+    readonly INVITE: "INVITE";
+}>;
+export declare const WA_NEWSLETTER_VIEW_ROLES: Readonly<{
+    readonly GUEST: "GUEST";
+    readonly SUBSCRIBER: "SUBSCRIBER";
+    readonly ADMIN: "ADMIN";
+    readonly OWNER: "OWNER";
+}>;
+export declare const WA_NEWSLETTER_MUTE_TYPES: Readonly<{
+    readonly ADMIN_ACTIVITY: "MUTE_ADMIN_ACTIVITY";
+    readonly FOLLOWER_ACTIVITY: "MUTE_FOLLOWER_ACTIVITY";
+}>;
+export declare const WA_NEWSLETTER_MUTE_VALUES: Readonly<{
+    readonly ON: "ON";
+    readonly OFF: "OFF";
+}>;
+export declare const WA_NEWSLETTER_SEND_TYPES: Readonly<{
+    readonly TEXT: "text";
+    readonly MEDIA: "media";
+    readonly REACTION: "reaction";
+    readonly REVOKE: "revoke";
+}>;
+export type WaNewsletterSendType = (typeof WA_NEWSLETTER_SEND_TYPES)[keyof typeof WA_NEWSLETTER_SEND_TYPES];
+export declare const WA_NEWSLETTER_RECEIVE_TYPES: Readonly<{
+    readonly TEXT: "NewsletterText";
+    readonly MEDIA: "NewsletterMedia";
+    readonly REACTION: "NewsletterReaction";
+    readonly REACTION_REVOKE: "NewsletterReactionRevoke";
+    readonly REVOKE: "NewsletterRevoke";
+    readonly EDIT: "NewsletterEdit";
+    readonly POLL_CREATION: "NewsletterPollCreation";
+    readonly POLL_VOTE: "NewsletterPollVote";
+    readonly POLL_RESULT_SNAPSHOT: "NewsletterPollResultSnapshot";
+    readonly QUIZ_CREATION: "NewsletterQuizCreation";
+    readonly QUESTION: "NewsletterQuestion";
+    readonly QUESTION_REPLY: "NewsletterQuestionReply";
+    readonly QUESTION_RESPONSE: "NewsletterQuestionResponse";
+    readonly WAMO_EMPTY: "NewsletterWAMOEmpty";
+}>;
+export type WaNewsletterReceiveType = (typeof WA_NEWSLETTER_RECEIVE_TYPES)[keyof typeof WA_NEWSLETTER_RECEIVE_TYPES];
+export declare const WA_NEWSLETTER_VERIFICATION_STATES: Readonly<{
+    readonly VERIFIED: "VERIFIED";
+    readonly UNVERIFIED: "UNVERIFIED";
+}>;

package/dist/types/protocol/nodes.d.ts

@@ -63,6 +63,22 @@ export declare const WA_NODE_TAGS: Readonly<{
     readonly MEMBERSHIP_APPROVAL_MODE: "membership_approval_mode";
     readonly GROUP_JOIN: "group_join";
     readonly ABPROPS: "abprops";
+    readonly PLAINTEXT: "plaintext";
+    readonly PRESENCE: "presence";
+    readonly CHATSTATE: "chatstate";
+    readonly CALL: "call";
+    readonly COMPOSING: "composing";
+    readonly PAUSED: "paused";
+    readonly BIZ: "biz";
+    readonly INTERACTIVE: "interactive";
+    readonly NATIVE_FLOW: "native_flow";
+    readonly BOT: "bot";
+    readonly META: "meta";
+    readonly STATUS: "status";
+    readonly USERNAME: "username";
+    readonly TEXT_STATUS: "text_status";
+    readonly DISAPPEARING_MODE: "disappearing_mode";
+    readonly BUSINESS: "business";
 }>;
 export declare const WA_IQ_TYPES: Readonly<{
     readonly GET: "get";
@@ -84,8 +100,12 @@ export declare const WA_XMLNS: Readonly<{
     readonly STATUS: "status";
     readonly GROUPS: "w:g2";
     readonly NEWSLETTER: "newsletter";
+    readonly TOS: "tos";
     readonly XMPP_PING: "urn:xmpp:ping";
     readonly WHATSAPP_PING: "w:p";
     readonly ABPROPS: "abt";
     readonly MEX: "w:mex";
+    readonly BOT: "bot";
+    readonly DISAPPEARING_MODE: "disappearing_mode";
+    readonly PASSIVE: "passive";
 }>;

package/dist/types/protocol/notification.d.ts

@@ -4,6 +4,20 @@ export declare const WA_NOTIFICATION_TYPES: Readonly<{
     readonly DEVICES: "devices";
     readonly SERVER: "server";
     readonly REGISTRATION: "registration";
+    readonly NEWSLETTER: "newsletter";
+    readonly BUSINESS: "business";
+    readonly PICTURE: "picture";
+}>;
+export declare const WA_BUSINESS_NOTIFICATION_TAGS: Readonly<{
+    readonly VERIFIED_NAME: "verified_name";
+    readonly REMOVE: "remove";
+    readonly PROFILE: "profile";
+    readonly PRODUCT_CATALOG: "product_catalog";
+    readonly SUBSCRIPTIONS: "subscriptions";
+    readonly FEATURE_FLAGS: "feature_flags";
+}>;
+export declare const WA_NEWSLETTER_NOTIFICATION_TAGS: Readonly<{
+    readonly LIVE_UPDATES: "live_updates";
 }>;
 export declare const WA_REGISTRATION_NOTIFICATION_TAGS: Readonly<{
     readonly WA_OLD_REGISTRATION: "wa_old_registration";
@@ -55,4 +69,6 @@ export declare const WA_GROUP_NOTIFICATION_TAGS: Readonly<{
     readonly GROUP_SAFETY_CHECK: "group_safety_check";
     readonly LIMIT_SHARING_ENABLED: "limit_sharing_enabled";
     readonly MISSING_PARTICIPANT_IDENTIFICATION: "missing_participant_identification";
+    readonly GROUP_HISTORY: "group_history";
+    readonly NO_GROUP_HISTORY: "no_group_history";
 }>;

package/dist/types/protocol/presence.d.ts

@@ -0,0 +1,16 @@
+export declare const WA_PRESENCE_TYPES: Readonly<{
+    readonly AVAILABLE: "available";
+    readonly UNAVAILABLE: "unavailable";
+    readonly SUBSCRIBE: "subscribe";
+}>;
+export declare const WA_PRESENCE_LAST_SENTINELS: Readonly<{
+    readonly DENY: "deny";
+    readonly NONE: "none";
+    readonly ERROR: "error";
+}>;
+export declare const WA_CHATSTATE_MEDIA: Readonly<{
+    readonly AUDIO: "audio";
+}>;
+export type WaPresenceType = (typeof WA_PRESENCE_TYPES)[keyof typeof WA_PRESENCE_TYPES];
+export type WaPresenceLastSentinel = (typeof WA_PRESENCE_LAST_SENTINELS)[keyof typeof WA_PRESENCE_LAST_SENTINELS];
+export type WaChatstateMedia = (typeof WA_CHATSTATE_MEDIA)[keyof typeof WA_CHATSTATE_MEDIA];

package/dist/types/protocol/status.d.ts

@@ -0,0 +1,7 @@
+export declare const WA_STATUS_DISTRIBUTION_SETTINGS: Readonly<{
+    readonly CONTACTS: "contacts";
+    readonly ALLOWLIST: "allowlist";
+    readonly DENYLIST: "denylist";
+    readonly CLOSE_FRIENDS: "close_friends";
+}>;
+export type WaStatusDistributionSetting = (typeof WA_STATUS_DISTRIBUTION_SETTINGS)[keyof typeof WA_STATUS_DISTRIBUTION_SETTINGS];

package/dist/types/retry/codec.d.ts

@@ -1,3 +1,8 @@
 import type { WaRetryReplayPayload } from './types';
+/**
+ * Encodes a {@link WaRetryReplayPayload} into the on-disk codec format used
+ * by the retry store. Supports the `plaintext`/`encrypted`/`opaque_node` modes.
+ */
 export declare function encodeRetryReplayPayload(payload: WaRetryReplayPayload): Uint8Array;
+/** Inverse of {@link encodeRetryReplayPayload}. Throws on bad magic/version. */
 export declare function decodeRetryReplayPayload(raw: Uint8Array): WaRetryReplayPayload;

package/dist/types/retry/index.d.ts

@@ -2,7 +2,7 @@ export { MAX_RETRY_ATTEMPTS, RETRY_KEYS_MIN_COUNT, RETRY_OUTBOUND_TTL_MS, RETRY_
 export type { WaRetryReasonCode } from './constants';
 export { mapRetryReasonFromError } from './reason';
 export { parseRetryReceiptRequest, pickRetryStateMax } from './parse';
-export type { WaParsedRetryRequest, WaRetryDecryptFailureContext, WaRetryEncryptedReplayPayload, WaRetryKey, WaRetryKeyBundle, WaRetryOpaqueNodeReplayPayload, WaRetryOutboundMessageRecord, WaRetryOutboundMode, WaRetryOutboundState, WaRetryPlaintextReplayPayload, WaRetryReceiptType, WaRetryReplayPayload, WaRetryStoredReplayPayload, WaRetrySignedKey } from './types';
+export type { WaParsedRetryRequest, WaRetryDecryptFailureContext, WaRetryEncryptedReplayPayload, WaRetryKey, WaRetryKeyBundle, WaRetryOpaqueNodeReplayPayload, WaRetryOutboundMessageRecord, WaRetryOutboundMode, WaRetryOutboundState, WaRetryPlaintextReplayPayload, WaRetryReceiptType, WaRetryReplayPayload, WaRetryStoredReplayPayload } from './types';
 export { decodeRetryReplayPayload, encodeRetryReplayPayload } from './codec';
 export { WaRetryReplayService, type WaRetryReplayServiceOptions, type WaRetryResendResult } from './replay';
 export { createOutboundRetryTracker, type OutboundRetryTrackHint, type OutboundRetryTracker } from './tracker';

package/dist/types/retry/parse.d.ts

@@ -1,6 +1,15 @@
 import type { WaParsedRetryRequest, WaRetryOutboundState } from './types';
 import type { BinaryNode } from '../transport/types';
+/**
+ * Parses an incoming `receipt` stanza into a {@link WaParsedRetryRequest}.
+ * Returns `null` when the stanza is not a retry/rekey-retry receipt; throws
+ * when required attrs/children are missing.
+ */
 export declare function parseRetryReceiptRequest(node: BinaryNode, options?: {
     readonly expectedToJids?: readonly string[];
 }): WaParsedRetryRequest | null;
+/**
+ * Returns whichever of `left`/`right` represents the more advanced retry
+ * state (according to the internal precedence rank).
+ */
 export declare function pickRetryStateMax(left: WaRetryOutboundState, right: WaRetryOutboundState): WaRetryOutboundState;

package/dist/types/retry/reason.d.ts

@@ -1,2 +1,7 @@
 import { type WaRetryReasonCode } from './constants';
+/**
+ * Maps a decryption/Signal error to the appropriate {@link WaRetryReasonCode}
+ * so an outbound retry receipt carries the correct `error` attribute.
+ * Returns `undefined` when no known reason matches.
+ */
 export declare function mapRetryReasonFromError(error: unknown): WaRetryReasonCode | undefined;

package/dist/types/retry/replay.d.ts

@@ -1,26 +1,40 @@
+import type { WaAuthCredentials } from '../auth/types';
 import type { Logger } from '../infra/log/types';
+import { type IcdcMeta } from '../message/crypto/icdc';
 import type { WaMessageClient } from '../message/WaMessageClient';
-import { type Proto } from '..';
 import type { WaRetryOutboundMessageRecord } from './types';
+import type { SignalSessionResolver } from '../signal/session/resolver';
 import type { SignalProtocol } from '../signal/session/SignalProtocol';
 export interface WaRetryReplayServiceOptions {
     readonly logger: Logger;
     readonly messageClient: WaMessageClient;
     readonly signalProtocol: SignalProtocol;
-    readonly getCurrentMeJid: () => string | null | undefined;
-    readonly getCurrentMeLid: () => string | null | undefined;
-    readonly getCurrentSignedIdentity: () => Proto.IADVSignedDeviceIdentity | null | undefined;
+    readonly sessionResolver: SignalSessionResolver;
+    readonly getCurrentCredentials: () => WaAuthCredentials | null;
+    readonly resolveUserIcdc?: (userJid: string) => Promise<IcdcMeta | null>;
 }
 export type WaRetryResendResult = 'resent' | 'ineligible';
+/**
+ * Replays a previously-sent outbound message in response to an incoming
+ * retry receipt. Dispatches to plaintext/encrypted/opaque-node handlers
+ * based on the stored payload shape.
+ */
 export declare class WaRetryReplayService {
     private readonly options;
     constructor(options: WaRetryReplayServiceOptions);
+    /**
+     * Resends `outbound` to `requesterJid`. Returns `'resent'` on a fresh
+     * send or `'ineligible'` when the cached payload cannot satisfy the
+     * request (e.g. requester not in the original device list).
+     */
     resendOutboundMessage(outbound: WaRetryOutboundMessageRecord, requesterJid: string, retryCount: number): Promise<WaRetryResendResult>;
     private resendPlaintextPayload;
+    private resolveSignedDeviceIdentity;
+    private refreshRetryPlaintext;
+    private safeUserJid;
     private resendGroupPlaintextPayload;
     private resendEncryptedPayload;
     private resendOpaquePayload;
-    private maybeWrapGroupRetryPlaintextForSelfDevice;
     private isRequesterCurrentAccount;
     private isOpaqueReplayCompatible;
 }

package/dist/types/retry/tracker.d.ts

@@ -5,15 +5,22 @@ import type { WaRetryStore } from '../store/contracts/retry.store';
 export type OutboundRetryTrackHint = {
     readonly messageIdHint?: string;
     readonly toJid?: string;
-    readonly type: string;
     readonly replayPayload: WaRetryReplayPayload;
-    readonly participantJid?: string;
-    readonly recipientJid?: string;
     readonly eligibleRequesterDeviceJids?: readonly string[];
 };
+/**
+ * Wraps message publishes and persists a replay record so the
+ * {@link WaRetryReplayService} can re-send the message later if a retry
+ * receipt arrives.
+ */
 export type OutboundRetryTracker = {
+    /**
+     * Runs `publish`, then upserts a retry-outbound record built from the
+     * tracking `hint`. Returns the publish result unchanged.
+     */
     track(hint: OutboundRetryTrackHint, publish: () => Promise<WaMessagePublishResult>): Promise<WaMessagePublishResult>;
 };
+/** Builds an {@link OutboundRetryTracker} backed by a {@link WaRetryStore}. */
 export declare function createOutboundRetryTracker(options: {
     readonly retryStore: WaRetryStore;
     readonly logger: Logger;

package/dist/types/retry/types.d.ts

@@ -1,5 +1,6 @@
+import type { WA_MESSAGE_TYPES } from '../protocol/message';
 import type { BinaryNode } from '../transport/types';
-export type WaRetryReceiptType = 'retry' | 'enc_rekey_retry';
+export type WaRetryReceiptType = typeof WA_MESSAGE_TYPES.RECEIPT_TYPE_RETRY | typeof WA_MESSAGE_TYPES.RECEIPT_TYPE_ENC_REKEY_RETRY;
 export type WaRetryOutboundMode = 'plaintext' | 'encrypted' | 'opaque_node';
 export type WaRetryOutboundState = 'pending' | 'delivered' | 'read' | 'played' | 'ineligible';
 export interface WaRetryKey {
@@ -7,9 +8,6 @@ export interface WaRetryKey {
     readonly publicKey: Uint8Array;
     readonly signature?: Uint8Array;
 }
-export type WaRetrySignedKey = WaRetryKey & {
-    readonly signature: Uint8Array;
-};
 export interface WaRetryKeyBundle {
     readonly identity: Uint8Array;
     readonly deviceIdentity?: Uint8Array;
@@ -44,6 +42,7 @@ export interface WaRetryPlaintextReplayPayload {
     readonly to: string;
     readonly type: string;
     readonly plaintext: Uint8Array;
+    readonly statusSetting?: string;
 }
 export interface WaRetryEncryptedReplayPayload {
     readonly mode: 'encrypted';
@@ -62,15 +61,11 @@ export type WaRetryStoredReplayPayload = Uint8Array | WaRetryReplayPayload;
 export interface WaRetryOutboundMessageRecord {
     readonly messageId: string;
     readonly toJid: string;
-    readonly participantJid?: string;
-    readonly recipientJid?: string;
     readonly eligibleRequesterDeviceJids?: readonly string[];
     readonly deliveredRequesterDeviceJids?: readonly string[];
-    readonly messageType: string;
     readonly replayMode: WaRetryOutboundMode;
     readonly replayPayload: WaRetryStoredReplayPayload;
     readonly state: WaRetryOutboundState;
-    readonly createdAtMs: number;
     readonly updatedAtMs: number;
     readonly expiresAtMs: number;
 }

package/dist/types/signal/api/SignalDeviceSyncApi.d.ts

@@ -15,6 +15,10 @@ export interface SignalLidSyncResult {
     readonly lidJid: string | null;
     readonly exists: boolean;
 }
+/**
+ * Resolves the device list and LID mapping for a set of users via the `usync`
+ * protocol. Concurrent calls for the same JIDs are deduplicated.
+ */
 export declare class SignalDeviceSyncApi {
     private readonly logger;
     private readonly query;
@@ -24,12 +28,28 @@ export declare class SignalDeviceSyncApi {
     private readonly generateSid;
     private readonly syncDedup;
     constructor(options: SignalDeviceSyncApiOptions);
+    /**
+     * Refreshes the device list for every JID in `userJids`. Returns the
+     * resolved per-user device JIDs (matches the on-store snapshot).
+     */
     syncDeviceList(userJids: readonly string[], timeoutMs?: number): Promise<readonly {
         readonly jid: string;
         readonly deviceJids: readonly string[];
     }[]>;
     private syncDeviceListInternal;
+    /**
+     * Looks up LIDs for a list of phone JIDs via a `lid` usync query. Returns
+     * one entry per input JID with `exists` indicating server-side presence.
+     */
     queryLidsByPhoneJids(phoneJids: readonly string[], timeoutMs?: number): Promise<readonly SignalLidSyncResult[]>;
+    /**
+     * Enriches existing device-list snapshots with the resolved LID equivalents
+     * so {@link WaDeviceListStore.findByAnyUserJid} can later match a retry
+     * receipt arriving in LID form against an eligible list stored in PN form
+     * (and vice versa). Skips users with no cached snapshot — the alt gets
+     * recorded on the next {@link syncDeviceList} sweep.
+     */
+    private propagateAltUserJids;
     private collectUsersToQuery;
     private makeDeviceSyncRequest;
     private makeLidSyncRequest;

package/dist/types/signal/api/SignalDigestSyncApi.d.ts

@@ -21,6 +21,11 @@ export interface SignalDigestPrefetchedLocalKeyBundle {
     readonly registrationInfo: RegistrationInfo;
     readonly signedPreKey: SignedPreKeyRecord;
 }
+/**
+ * Validates the local Signal key bundle (identity, signed prekey, one-time
+ * prekey ids) against the server-side digest. Used to detect drift after a
+ * crash or partial sync and decide whether to re-upload.
+ */
 export declare class SignalDigestSyncApi {
     private readonly logger;
     private readonly query;
@@ -29,6 +34,11 @@ export declare class SignalDigestSyncApi {
     private readonly defaultTimeoutMs;
     private readonly hostDomain;
     constructor(options: SignalDigestSyncApiOptions);
+    /**
+     * Compares the local Signal key bundle digest with the server's. Returns
+     * a structured result describing whether anything diverged and which
+     * field caused the mismatch.
+     */
     validateLocalKeyBundle(timeoutMs?: number): Promise<SignalDigestValidationResult>;
     validateLocalKeyBundle(prefetched?: SignalDigestPrefetchedLocalKeyBundle, timeoutMs?: number): Promise<SignalDigestValidationResult>;
     private parseDigestPayload;

package/dist/types/signal/api/SignalIdentitySyncApi.d.ts

@@ -13,6 +13,11 @@ interface SignalIdentitySyncApiOptions {
     readonly defaultTimeoutMs?: number;
     readonly hostDomain?: string;
 }
+/**
+ * Fetches identity keys for a list of JIDs from the server and persists them
+ * into the identity store. Concurrent calls for the same JID set are
+ * deduplicated.
+ */
 export declare class SignalIdentitySyncApi {
     private readonly logger;
     private readonly query;
@@ -21,6 +26,10 @@ export declare class SignalIdentitySyncApi {
     private readonly hostDomain;
     private readonly syncDedup;
     constructor(options: SignalIdentitySyncApiOptions);
+    /**
+     * Fetches and persists identity keys for `targetJids`. Returns one entry
+     * per JID the server resolved; missing/erroring users are skipped.
+     */
     syncIdentityKeys(targetJids: readonly string[], timeoutMs?: number): Promise<readonly SignalIdentitySyncEntry[]>;
     private syncIdentityKeysInternal;
     private parseIdentitySyncResponse;

package/dist/types/signal/api/SignalMissingPreKeysSyncApi.d.ts

@@ -27,11 +27,19 @@ export type SignalMissingPreKeysUserResult = {
     readonly errorCode?: number;
     readonly errorText: string;
 };
+/**
+ * Fetches missing prekey bundles for specific (user, device, registration id)
+ * triples – used during message encryption when a Signal session is missing.
+ */
 export declare class SignalMissingPreKeysSyncApi {
     private readonly logger;
     private readonly query;
     private readonly defaultTimeoutMs;
     constructor(options: SignalMissingPreKeysSyncApiOptions);
+    /**
+     * Fetches prekey bundles for the requested `targets` in a single IQ.
+     * Returns either a per-device bundle list or an error envelope per user.
+     */
     fetchMissingPreKeys(targets: readonly SignalMissingPreKeysTarget[], timeoutMs?: number): Promise<readonly SignalMissingPreKeysUserResult[]>;
     private parseFetchMissingPreKeysResponse;
     private parseUserDevices;

package/dist/types/signal/api/SignalRotateKeyApi.d.ts

@@ -7,12 +7,22 @@ interface SignalRotateKeyApiOptions {
     readonly signalStore: WaSignalStore;
     readonly defaultTimeoutMs?: number;
 }
+/**
+ * Generates a fresh signed prekey and uploads it to the server. Handles the
+ * `406`/`409`/`5xx` error codes by signaling whether a digest re-validation
+ * is required.
+ */
 export declare class SignalRotateKeyApi {
     private readonly logger;
     private readonly query;
     private readonly signalStore;
     private readonly defaultTimeoutMs;
     constructor(options: SignalRotateKeyApiOptions);
+    /**
+     * Rotates the signed prekey by generating a new one (next key id) and
+     * uploading it. Returns `shouldDigestKey: true` when the caller should
+     * re-run a digest validation after the rotation.
+     */
     rotateSignedPreKey(timeoutMs?: number): Promise<{
         shouldDigestKey: boolean;
         errorCode?: number;