zapo-js 0.2.0 → 1.0.0

package/dist/types/crypto/core/hkdf.d.ts

@@ -1,2 +1,10 @@
-export declare function hkdf(ikm: Uint8Array, salt: Uint8Array | null, info: Uint8Array | string, outLength: number): Promise<Uint8Array>;
-export declare function hkdfSplit(ikm: Uint8Array, salt: Uint8Array | null, info: string): Promise<readonly [Uint8Array, Uint8Array]>;
+/**
+ * HKDF (HMAC-SHA-256) – derives `outLength` bytes from `ikm` using the given
+ * `salt` (empty bytes when `null`) and `info` context.
+ */
+export declare function hkdf(ikm: Uint8Array, salt: Uint8Array | null, info: Uint8Array, outLength: number): Uint8Array;
+/**
+ * Derives a 64-byte HKDF output and returns it split into two 32-byte halves
+ * (Signal/WhatsApp pair-key derivation pattern).
+ */
+export declare function hkdfSplit(ikm: Uint8Array, salt: Uint8Array | null, info: Uint8Array): readonly [Uint8Array, Uint8Array];

package/dist/types/crypto/core/index.d.ts

@@ -5,6 +5,7 @@ export { Ed25519 } from '../curves/Ed25519';
 export { X25519 } from '../curves/X25519';
 export { hkdf, hkdfSplit } from '../core/hkdf';
 export { toSerializedPubKey, toRawPubKey, prependVersion, readVersionedContent } from '../core/keys';
-export { buildNonce } from '../core/nonce';
+export { writeNonceCounter } from '../core/nonce';
 export { randomBytesAsync, randomFillAsync, randomIntAsync } from '../core/random';
-export { type CryptoKey, sha1, sha256, sha512, importAesGcmKey, aesGcmEncrypt, aesGcmDecrypt, importAesCbcKey, aesCbcEncrypt, aesCbcDecrypt, importHmacKey, importHmacSha512Key, hmacSign, pbkdf2DeriveAesCtrKey, aesCtrEncrypt, aesCtrDecrypt } from '../core/primitives';
+export { sha1, sha256, sha512, md5Bytes, aesGcmEncrypt, aesGcmDecrypt, aesCbcEncrypt, aesCbcDecrypt, aesCtrEncrypt, aesCtrDecrypt, hmacSha256Sign, hmacSha512Sign, pbkdf2Sha256 } from '../core/primitives';
+export { xeddsaSign, xeddsaVerify } from '../core/xeddsa';

package/dist/types/crypto/core/keys.d.ts

@@ -6,10 +6,6 @@ export declare function toSerializedPubKey(key: Uint8Array): Uint8Array;
  * Converts a 33-byte serialized public key to 32-byte raw format
  */
 export declare function toRawPubKey(key: Uint8Array): Uint8Array;
-/**
- * Creates a version byte from high and low nibbles
- */
-export declare function versionByte(high: number, low: number): number;
 /**
  * Prepends a version byte to content
  */

package/dist/types/crypto/core/nonce.d.ts

@@ -1,7 +1,6 @@
 /**
- * Builds a 12-byte nonce for AES-GCM encryption with counter in the last 4 bytes.
- * Allocates a new buffer per call because concurrent Noise encrypt/decrypt operations
- * may hold references to different nonces simultaneously.
- * Throws if counter exceeds uint32 range to prevent nonce reuse.
+ * Writes a 32-bit big-endian `counter` into the last 4 bytes of a 12-byte
+ * AES-GCM nonce buffer. The first 8 bytes are left untouched so callers can
+ * reuse a per-instance scratch buffer in hot paths.
  */
-export declare function buildNonce(counter: number): Uint8Array;
+export declare function writeNonceCounter(out: Uint8Array, counter: number): void;

package/dist/types/crypto/core/primitives.d.ts

@@ -1,24 +1,35 @@
+import { type KeyObject } from 'node:crypto';
+export type HashInput = Uint8Array | readonly Uint8Array[];
+/** Computes the SHA-1 digest of `value`. Accepts a single chunk or array of chunks. */
+export declare function sha1(value: HashInput): Uint8Array;
+/** Computes the SHA-256 digest of `value`. */
+export declare function sha256(value: HashInput): Uint8Array;
+/** Computes the SHA-512 digest of `value`. */
+export declare function sha512(value: HashInput): Uint8Array;
+/** Computes the MD5 digest of `input`, accepting a string or raw chunks. */
+export declare function md5Bytes(input: string | HashInput): Uint8Array;
+export type AesKey = Uint8Array | KeyObject;
 /**
- * Low-level crypto primitives using WebCrypto API
+ * AES-256-GCM encrypt. The 16-byte auth tag is appended to the ciphertext.
+ * Pass `aad` when binding the ciphertext to associated data.
  */
-import { webcrypto } from 'node:crypto';
+export declare function aesGcmEncrypt(key: AesKey, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Uint8Array;
 /**
- * Re-exported CryptoKey type so consumers don't need to import from 'node:crypto'
+ * AES-256-GCM decrypt. Expects the 16-byte auth tag appended to the
+ * ciphertext (matching {@link aesGcmEncrypt}'s layout). Throws on auth failure.
  */
-export type CryptoKey = webcrypto.CryptoKey;
-export declare function sha256(value: Uint8Array): Promise<Uint8Array>;
-export declare function sha1(value: Uint8Array): Promise<Uint8Array>;
-export declare function sha512(value: Uint8Array): Promise<Uint8Array>;
-export declare function md5Bytes(input: string): Uint8Array;
-export declare function importAesGcmKey(raw: Uint8Array, usages: ('encrypt' | 'decrypt')[]): Promise<webcrypto.CryptoKey>;
-export declare function aesGcmEncrypt(key: webcrypto.CryptoKey, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
-export declare function aesGcmDecrypt(key: webcrypto.CryptoKey, nonce: Uint8Array, ciphertext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
-export declare function importAesCbcKey(keyBytes: Uint8Array): Promise<webcrypto.CryptoKey>;
-export declare function aesCbcEncrypt(key: webcrypto.CryptoKey, iv: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
-export declare function aesCbcDecrypt(key: webcrypto.CryptoKey, iv: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>;
-export declare function importHmacKey(keyBytes: Uint8Array): Promise<webcrypto.CryptoKey>;
-export declare function importHmacSha512Key(keyBytes: Uint8Array): Promise<webcrypto.CryptoKey>;
-export declare function hmacSign(key: webcrypto.CryptoKey, data: Uint8Array): Promise<Uint8Array>;
-export declare function pbkdf2DeriveAesCtrKey(password: Uint8Array, salt: Uint8Array, iterations: number): Promise<CryptoKey>;
-export declare function aesCtrEncrypt(key: CryptoKey, counter: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
-export declare function aesCtrDecrypt(key: CryptoKey, counter: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>;
+export declare function aesGcmDecrypt(key: AesKey, nonce: Uint8Array, ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array;
+/** AES-256-CBC encrypt with PKCS#7 padding (default Node behavior). */
+export declare function aesCbcEncrypt(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Uint8Array;
+/** AES-256-CBC decrypt with PKCS#7 padding. */
+export declare function aesCbcDecrypt(key: Uint8Array, iv: Uint8Array, ciphertext: Uint8Array): Uint8Array;
+/** AES-256-CTR encrypt with the given 16-byte counter. */
+export declare function aesCtrEncrypt(key: Uint8Array, counter: Uint8Array, plaintext: Uint8Array): Uint8Array;
+/** AES-256-CTR decrypt with the given 16-byte counter. */
+export declare function aesCtrDecrypt(key: Uint8Array, counter: Uint8Array, ciphertext: Uint8Array): Uint8Array;
+/** Computes the HMAC-SHA-256 MAC of `data` keyed by `key`. */
+export declare function hmacSha256Sign(key: Uint8Array, data: HashInput): Uint8Array;
+/** Computes the HMAC-SHA-512 MAC of `data` keyed by `key`. */
+export declare function hmacSha512Sign(key: Uint8Array, data: HashInput): Uint8Array;
+/** PBKDF2 over HMAC-SHA-256 – derives `length` bytes from `password` + `salt`. */
+export declare function pbkdf2Sha256(password: Uint8Array, salt: Uint8Array, iterations: number, length: number): Promise<Uint8Array>;

package/dist/types/crypto/core/random.d.ts

@@ -1,3 +1,9 @@
-export declare function randomBytesAsync(size: number): Promise<Uint8Array>;
+/**
+ * Cryptographically fills `target` (optionally a sub-range) with random bytes.
+ * Resolves to the same `target` reference for chaining.
+ */
 export declare function randomFillAsync(target: Uint8Array, offset?: number, size?: number): Promise<Uint8Array>;
+/** Returns a cryptographically secure integer in `[min, max)`. */
 export declare const randomIntAsync: (min: number, max: number) => Promise<number>;
+/** Returns `size` cryptographically secure random bytes. */
+export declare const randomBytesAsync: (size: number) => Promise<Uint8Array>;

package/dist/types/crypto/core/xeddsa.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Verifies an XEdDSA signature over `message` against an X25519 (Montgomery)
+ * public key, converting to the Edwards form internally. Returns `false`
+ * on shape mismatch instead of throwing.
+ */
+export declare function xeddsaVerify(curvePublicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): Promise<boolean>;
+/**
+ * Signs `message` with an X25519 (Montgomery) private key using the XEdDSA
+ * construction. Returns a 64-byte signature.
+ */
+export declare function xeddsaSign(privateKey: Uint8Array, message: Uint8Array): Promise<Uint8Array>;

package/dist/types/crypto/curves/Ed25519.d.ts

@@ -1,7 +1,13 @@
 import { type SignalKeyPair } from '../curves/types';
+/**
+ * Ed25519 sign/verify backed by Node's native primitives. All operations are
+ * async to keep crypto off the event loop.
+ */
 export declare class Ed25519 {
+    /** Generates a fresh Ed25519 key pair. */
     static generateKeyPair(): Promise<SignalKeyPair>;
-    static keyPairFromPrivateKey(privKey: Uint8Array): Promise<SignalKeyPair>;
+    /** Signs `message` with a 32-byte Ed25519 private key. Returns a 64-byte signature. */
     static sign(message: Uint8Array, privKey: Uint8Array): Promise<Uint8Array>;
+    /** Verifies an Ed25519 `signature` over `message` against a 32-byte public key. */
     static verify(message: Uint8Array, signature: Uint8Array, pubKey: Uint8Array): Promise<boolean>;
 }

package/dist/types/crypto/curves/X25519.d.ts

@@ -1,8 +1,27 @@
 import { type SignalKeyPair } from '../curves/types';
+/**
+ * Applies the standard curve25519 scalar clamping in place and returns the
+ * same buffer for chaining. Throws on non-32-byte inputs.
+ */
 export declare function clampCurvePrivateKeyInPlace(privateKey: Uint8Array): Uint8Array;
+/**
+ * Converts a 32-byte Montgomery (curve25519) public key to its Edwards form
+ * for XEdDSA verification, applying the supplied `signBit` (`0x80` mask).
+ * Throws on the field-`p-1` low-order point.
+ */
 export declare function montgomeryToEdwardsPublic(curvePublicKey: Uint8Array, signBit: number): Uint8Array;
+/**
+ * X25519 key-pair generation and Diffie-Hellman scalar multiplication
+ * backed by Node's native primitives.
+ */
 export declare class X25519 {
+    /** Generates a fresh X25519 key pair. */
     static generateKeyPair(): Promise<SignalKeyPair>;
-    static keyPairFromPrivateKey(privKey: Uint8Array): Promise<SignalKeyPair>;
+    /** Derives the matching public key from a 32-byte X25519 private key. */
+    static keyPairFromPrivateKey(privKey: Uint8Array): SignalKeyPair;
+    /**
+     * Computes the X25519 shared secret between `privKey` and `pubKey`.
+     * Uses Node's async DH path when supported, otherwise falls back to sync.
+     */
     static scalarMult(privKey: Uint8Array, pubKey: Uint8Array): Promise<Uint8Array>;
 }

package/dist/types/crypto/curves/constants.d.ts

@@ -1,2 +1,4 @@
-export declare const X25519_PKCS8_PREFIX: Uint8Array<ArrayBufferLike>;
-export declare const ED25519_PKCS8_PREFIX: Uint8Array<ArrayBufferLike>;
+export declare const X25519_PKCS8_PREFIX: Readonly<Uint8Array>;
+export declare const X25519_SPKI_PREFIX: Readonly<Uint8Array>;
+export declare const ED25519_PKCS8_PREFIX: Readonly<Uint8Array>;
+export declare const ED25519_SPKI_PREFIX: Readonly<Uint8Array>;

package/dist/types/crypto/curves/types.d.ts

@@ -1,10 +1,5 @@
-import type { webcrypto } from 'node:crypto';
 export interface SignalKeyPair {
     readonly pubKey: Uint8Array;
     readonly privKey: Uint8Array;
 }
-export interface SubtleKeyPair {
-    readonly privateKey: webcrypto.CryptoKey;
-    readonly publicKey: webcrypto.CryptoKey;
-}
 export declare function pkcs8FromRawPrivate(prefix: Uint8Array, raw: Uint8Array): Uint8Array;

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

@@ -1,2 +1,3 @@
 export * from './core';
 export { X25519 } from './curves/X25519';
+export type { SignalKeyPair } from './curves/types';

package/dist/types/crypto/math/constants.d.ts

@@ -3,7 +3,6 @@ import type { ExtendedPoint } from '../math/types';
 export declare const FIELD_P: bigint;
 export declare const GROUP_L: bigint;
 export declare const FE_TWO_D: Fe;
-export declare const FE_ZERO: Fe;
 export declare const FE_ONE: Fe;
 export declare const BASE_POINT: ExtendedPoint;
 export declare const IDENTITY_POINT: ExtendedPoint;

package/dist/types/crypto/math/mod.d.ts

@@ -1,3 +1,2 @@
 export declare function mod(value: bigint, modulus?: bigint): bigint;
 export declare function modGroup(value: bigint): bigint;
-export declare function modInv(value: bigint, modulus?: bigint): bigint;

package/dist/types/index.d.ts

@@ -1,12 +1,39 @@
 export { WaClient } from '@client';
-export type { WaClientEventMap, WaClientOptions, WaClientProxyOptions, WaHistorySyncChunkEvent, WaHistorySyncOptions, WaWriteBehindOptions } from '@client';
+export type { WaClientEventMap, WaClientOptions, WaClientProxyOptions, WaDownloadMediaOptions, WaHistorySyncChunkEvent, WaHistorySyncOptions, WaWriteBehindOptions } from './client/types';
+export type { WaMessageCoordinator } from './client/coordinators/WaMessageCoordinator';
+export type { WaAccountTakeoverNoticeEvent, WaAppStateMutationEvent, WaAppStateMutationSource, WaBusinessEvent, WaBusinessEventAction, WaBusinessProfileResult, WaConnectionEvent, WaGroupEvent, WaGroupEventAction, WaGroupEventLinkedGroup, WaGroupEventMembershipRequest, WaGroupEventParticipant, WaGroupEventSubgroupSuggestion, WaIgnoreKey, WaIgnoreKeyContext, WaIgnoreKeyPredicate, WaIgnoreStanzaKind, WaIncomingAddonEvent, WaIncomingBaseEvent, WaIncomingBotChunkEvent, WaIncomingCallEvent, WaIncomingChatstateEvent, WaIncomingErrorStanzaEvent, WaIncomingFailureEvent, WaIncomingMessageEvent, WaIncomingMessageKey, WaIncomingNewsletterEvent, WaIncomingNewsletterMessageUpdateEvent, WaIncomingNodeHandler, WaIncomingNodeHandlerRegistration, WaIncomingNotificationEvent, WaIncomingPresenceEvent, WaIncomingProtocolMessageEvent, WaIncomingReceiptEvent, WaIncomingStanzaFilter, WaIncomingUnhandledStanzaEvent, WaMexLidChangeEvent, WaMexMessageCappingEvent, WaMexMessageCappingStatus, WaMexNotificationEvent, WaMexNotificationGraphQlError, WaMexNotificationOperationName, WaMexNotificationUnknownEvent, WaMexOwnUsernameSyncEvent, WaMexTextStatusUpdateEvent, WaMexTextStatusUpdateHintEvent, WaMexUsernameDeleteEvent, WaMexUsernameSetEvent, WaMexUsernameUpdateHintEvent, WaOfflineResumeEvent, WaPictureEvent, WaPictureEventAction, WaPrivacyTokenUpdateEvent, WaReceiptStatus, WaRegistrationCodeEvent, WaSendMessageOptions, WaVerifiedNameResult, WaAddonKind, WaNewsletterEventAction, WaNewsletterMessageUpdate, WaNewsletterPollVoteEntry, WaNewsletterReactionEntry } from './client/types';
+export type { WaAppStateMutationCoordinator, WaBroadcastListParticipant, WaSetBroadcastListInput, WaSetStatusPrivacyInput } from './client/coordinators/WaAppStateMutationCoordinator';
+export type { WaBotCoordinator, WaBotInfo, WaBotPosingAsProfessional, WaBotProfileCommand, WaBotProfilePrompt, WaBotProfileResult, WaBotPromptOptions, WaGetBotProfileOptions } from './client/coordinators/WaBotCoordinator';
+export type { WaBroadcastListCoordinator, WaSendBroadcastListMessageInput } from './client/coordinators/WaBroadcastListCoordinator';
+export type { WaBusinessCoordinator, WaVerifiedNameBatchEntry } from './client/coordinators/WaBusinessCoordinator';
+export type { WaUploadMediaSource } from './client/media';
+export type { WaEditBusinessProfileInput } from './transport/node/builders/business';
+export type { WaEmailCoordinator, WaEmailStatus, WaEmailVerifyCodeResult } from './client/coordinators/WaEmailCoordinator';
+export type { WaCommunityCreateOptions, WaCommunitySubGroup, WaCommunitySubGroupResult, WaCommunitySubGroupsResult, WaGroupCoordinator, WaGroupCreateOptions, WaGroupMetadata, WaGroupParticipant, WaLinkSubGroupsResult, WaMembershipRequest, WaUnlinkSubGroupsResult } from './client/coordinators/WaGroupCoordinator';
+export type { WaNewsletterAdminInfo, WaNewsletterAdminInviteInput, WaNewsletterAdminInviteResult, WaNewsletterAdminProfile, WaNewsletterCapabilityExposure, WaNewsletterCoordinator, WaNewsletterCreateInput, WaNewsletterDehydratedMetadata, WaNewsletterDirectoryCategoriesPreviewOptions, WaNewsletterDirectoryCategoryPreview, WaNewsletterDirectoryListOptions, WaNewsletterDirectoryResults, WaNewsletterDirectorySearchOptions, WaNewsletterDirectoryView, WaNewsletterFetchOptions, WaNewsletterFollower, WaNewsletterFollowersOptions, WaNewsletterFollowersPage, WaNewsletterInsightMetricRequest, WaNewsletterMetadata, WaNewsletterMuteInput, WaNewsletterPicture, WaNewsletterPollVoter, WaNewsletterReactInput, WaNewsletterReactionSenders, WaNewsletterRecommendedOptions, WaNewsletterRevokeInput, WaNewsletterSendOptions, WaNewsletterSendResult, WaNewsletterSimilarOptions, WaNewsletterUpdateInput, WaNewsletterViewReceiptInput, WaNewsletterVotePollInput, WaPageInfo } from './client/coordinators/WaNewsletterCoordinator';
 export type { WaBlocklistResult, WaPrivacyCoordinator, WaPrivacyDisallowedListResult, WaPrivacySettings } from './client/coordinators/WaPrivacyCoordinator';
+export type { WaDisappearingModeResult, WaOwnUsernameResult, WaProfileCoordinator, WaProfileInfo, WaProfilePictureResult, WaProfileStatusResult, WaSetTextStatusInput, WaSetUsernameInput, WaTextStatusResult, WaUsernameResult } from './client/coordinators/WaProfileCoordinator';
+export type { WaProfilePictureType } from './transport/node/builders/profile';
+export { parseUsyncResultEnvelope } from './transport/node/builders/usync';
+export type { WaUsyncProtocolError, WaUsyncResultEnvelope } from './transport/node/builders/usync';
+export type { WaSendStatusInput, WaStatusCoordinator } from './client/coordinators/WaStatusCoordinator';
+export type { WaEncryptedMessageInput, WaMessageAckMetadata, WaMessageKey, WaMessagePublishOptions, WaMessagePublishResult, WaMessageRef, WaMessageTargetInput, WaSendEditKey, WaSendEventLocation, WaSendEventMessage, WaSendEventParent, WaSendEventResponseMessage, WaSendEventResponseType, WaSendKeepMessage, WaSendMediaMessage, WaSendMessageContent, WaSendPinMessage, WaSendPollMessage, WaSendPollOptionInput, WaSendPollParent, WaSendPollVoteMessage, WaSendReactionMessage, WaSendReceiptEventOptions, WaSendReceiptInput, WaSendReceiptOptions, WaSendRevokeMessage, WaSendStickerPackMessage, WaSendStickerPackStickerInput, WaSendStickerPackTrayIcon, WaSendTextMessage } from './message/types';
+export { getContentType, resolveMessageTarget } from './message/encode/content';
+export type { WaSendContextInfo } from './message/context-info';
+export type { WaLinkPreviewFetcher, WaLinkPreviewOptions, WaLinkPreviewOverride, WaLinkPreviewResolved, WaLinkPreviewThumbnailBytes, WaLinkPreviewThumbnailInput, WaLinkPreviewThumbnailStream, WaLinkPreviewType } from './message/addons/link-preview/types';
+export type { SignalLidSyncResult } from './signal/api/SignalDeviceSyncApi';
+export type { WaAuthCredentials, WaVersionResolver } from './auth/types';
+export type { BinaryNode } from './transport/types';
+export { fetchLatestWaWebVersion } from './transport/wa-web-version-fetcher';
+export type { WaFetchLatestWebVersionOptions, WaLatestWebVersion } from './transport/wa-web-version-fetcher';
 export { ConsoleLogger } from './infra/log/ConsoleLogger';
 export { PinoLogger, createPinoLogger } from './infra/log/PinoLogger';
 export type { PinoLoggerOptions } from './infra/log/PinoLogger';
+export { createNoopLogger } from './infra/log/types';
 export type { Logger, LogLevel } from './infra/log/types';
-export { createStore } from '@store';
-export type { WaAppStateCollectionStoreState, WaAppStateStore, WaAuthStore, WaContactStore, WaCreateStoreOptions, WaDeviceListSnapshot, WaDeviceListStore, WaMessageStore, WaParticipantsSnapshot, WaParticipantsStore, WaRetryStore, WaSenderKeyStore, WaSignalStore, WaStoredContactRecord, WaStoredMessageRecord, WaStoredThreadRecord, WaStore, WaStoreBackend, WaStoreSession, WaThreadStore } from '@store';
-export { getLoginIdentity, getWaCompanionPlatformId, getWaMediaHkdfInfo, isGroupJid, normalizeDeviceJid, normalizeRecipientJid, parsePhoneJid, parseSignalAddressFromJid, splitJid, toUserJid, WA_ACCOUNT_SYNC_PROTOCOLS, WA_APP_STATE_COLLECTIONS, WA_APP_STATE_COLLECTION_STATES, WA_APP_STATE_ERROR_CODES, WA_APP_STATE_KDF_INFO, WA_APP_STATE_KEY_TYPES, WA_APP_STATE_SYNC_DATA_TYPE, WA_BROWSERS, WA_COMPANION_PLATFORM_IDS, WA_DEFAULTS, WA_DIRTY_PROTOCOLS, WA_DIRTY_TYPES, WA_DISCONNECT_REASONS, WA_IQ_TYPES, WA_LOGOUT_REASONS, WA_MESSAGE_TAGS, WA_MESSAGE_TYPES, WA_MEDIA_HKDF_INFO, WA_NODE_TAGS, WA_PAIRING_KDF_INFO, WA_PREVIEW_MEDIA_HKDF_INFO, WA_READY_STATES, WA_RETRYABLE_ACK_CODES, WA_SIGNALING, WA_STREAM_SIGNALING, WA_SUPPORTED_DIRTY_TYPES, WA_PRIVACY_CATEGORIES, WA_PRIVACY_CATEGORY_TO_SETTING, WA_PRIVACY_DISALLOWED_LIST_CATEGORIES, WA_PRIVACY_SETTING_TO_CATEGORY, WA_PRIVACY_TAGS, WA_PRIVACY_VALUES, WA_XMLNS } from '@protocol';
-export type { WaPrivacyCategory, WaPrivacySettingName, WaPrivacyValue } from '@protocol';
+export { createStore, WaAuthMemoryStore } from '@store';
+export type { WaAppStateCollectionStoreState, WaAppStateStore, WaAuthStore, WaContactStore, WaCreateStoreOptions, WaCreateStoreOptionsStrict, WaDeviceListSnapshot, WaDeviceListStore, WaGroupMetadataSnapshot, WaGroupMetadataStore, WaMessageStore, WaRetryStore, WaSenderKeyStore, WaSessionStore, WaSignalStore, WaIdentityStore, WaPreKeyStore, WaStoredContactRecord, WaStoredMessageRecord, WaStoredThreadRecord, WaStore, WaStoreBackend, WaStoreSession, WaThreadStore } from '@store';
+export { delay } from './util/async';
+export { buildDeviceJid, canonicalizeSignalJid, canonicalizeSignalServer, getLoginIdentity, getWaCompanionPlatformId, getWaMediaHkdfInfo, isBotJid, isBroadcastJid, isGroupJid, isGroupOrBroadcastJid, isHostedDeviceId, isHostedDeviceJid, isHostedServer, isLidJid, isNewsletterJid, isStatusBroadcastJid, isUserJid, normalizeDeviceJid, normalizeRecipientJid, parseJidFull, parsePhoneJid, parseSignalAddressFromJid, signalAddressKey, splitJid, toUserJid, WA_ACCOUNT_SYNC_PROTOCOLS, WA_APP_STATE_COLLECTIONS, WA_APP_STATE_COLLECTION_STATES, WA_APP_STATE_ERROR_CODES, WA_APP_STATE_KDF_INFO, WA_APP_STATE_KEY_TYPES, WA_APP_STATE_SYNC_DATA_TYPE, WA_BROWSERS, WA_BUSINESS_HOURS_DAYS, WA_BUSINESS_HOURS_MODES, WA_COMPANION_PLATFORM_IDS, WA_DEFAULTS, WA_DIRTY_PROTOCOLS, WA_DIRTY_TYPES, WA_DISCONNECT_REASONS, WA_IQ_TYPES, WA_LOGOUT_REASONS, WA_MESSAGE_TAGS, WA_MESSAGE_TYPES, WA_MEDIA_HKDF_INFO, WA_NODE_TAGS, WA_PAIRING_KDF_INFO, WA_PREVIEW_MEDIA_HKDF_INFO, WA_READY_STATES, WA_RETRYABLE_ACK_CODES, WA_SIGNALING, WA_STREAM_SIGNALING, WA_SUPPORTED_DIRTY_TYPES, WA_PRIVACY_CATEGORIES, WA_PRIVACY_CATEGORY_TO_SETTING, WA_PRIVACY_DISALLOWED_LIST_CATEGORIES, WA_PRIVACY_SETTING_TO_CATEGORY, WA_PRIVACY_TAGS, WA_PRIVACY_VALUES, WA_XMLNS } from '@protocol';
+export type { ParsedJid, WaBusinessHoursDay, WaBusinessHoursMode, WaConnectionCode, WaConnectionOpenReason, WaDisconnectReason, WaFailureReasonCode, WaLogoutReason, WaPrivacyCategory, WaPrivacySettingName, WaPrivacyValue, WaStreamErrorCode } from '@protocol';
 export { proto } from '.';

package/dist/types/infra/log/ConsoleLogger.d.ts

@@ -1,12 +1,29 @@
-import type { LogLevel, Logger } from '../log/types';
+import type { Logger, LogLevel } from '../log/types';
+/**
+ * Default zero-dependency {@link Logger} that writes structured records to
+ * the standard `console` sinks. Messages below the configured `level` are
+ * dropped without formatting cost.
+ */
 export declare class ConsoleLogger implements Logger {
     readonly level: LogLevel;
     private readonly minLevelPriority;
-    constructor(level?: LogLevel);
+    private readonly bindings;
+    /** @param level Minimum level to emit. Defaults to `'info'`. */
+    constructor(level?: LogLevel, bindings?: Readonly<Record<string, unknown>> | null);
+    /** Emits a `trace` record. */
     trace(message: string, context?: Record<string, unknown>): void;
+    /** Emits a `debug` record. */
     debug(message: string, context?: Record<string, unknown>): void;
+    /** Emits an `info` record. */
     info(message: string, context?: Record<string, unknown>): void;
+    /** Emits a `warn` record. */
     warn(message: string, context?: Record<string, unknown>): void;
+    /** Emits an `error` record. */
     error(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Returns a derived logger with `bindings` merged into the parent's
+     * bindings. Per-call context still wins on key conflicts.
+     */
+    child(bindings: Readonly<Record<string, unknown>>): Logger;
     private write;
 }

package/dist/types/infra/log/PinoLogger.d.ts

@@ -1,4 +1,4 @@
-import type { LogLevel, Logger } from '../log/types';
+import type { Logger, LogLevel } from '../log/types';
 type PinoLikeLogger = {
     level: string;
     trace: (...args: unknown[]) => void;
@@ -6,25 +6,79 @@ type PinoLikeLogger = {
     info: (...args: unknown[]) => void;
     warn: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
+    child?: (bindings: Readonly<Record<string, unknown>>) => PinoLikeLogger;
 };
+export interface PinoPrettyOptions {
+    readonly colorize?: boolean;
+    readonly colorizeObjects?: boolean;
+    readonly translateTime?: boolean | string;
+    readonly ignore?: string;
+    readonly include?: string;
+    readonly singleLine?: boolean;
+    readonly hideObject?: boolean;
+    readonly levelFirst?: boolean;
+    readonly messageKey?: string;
+    readonly messageFormat?: string;
+    readonly timestampKey?: string;
+    readonly levelKey?: string;
+    readonly levelLabel?: string;
+    readonly minimumLevel?: LogLevel;
+    readonly errorLikeObjectKeys?: readonly string[];
+    readonly errorProps?: string;
+    readonly customColors?: string;
+    readonly customLevels?: string;
+    readonly useOnlyCustomProps?: boolean;
+    readonly crlf?: boolean;
+    readonly destination?: number | string;
+    readonly append?: boolean;
+    readonly mkdir?: boolean;
+    readonly sync?: boolean;
+    readonly [key: string]: unknown;
+}
 export interface PinoLoggerOptions {
     readonly level?: LogLevel;
     readonly name?: string;
     readonly base?: Readonly<Record<string, unknown>> | null;
     readonly pinoOptions?: Readonly<Record<string, unknown>>;
     readonly pretty?: boolean;
-    readonly prettyOptions?: Readonly<Record<string, unknown>>;
+    readonly prettyOptions?: PinoPrettyOptions;
 }
+/**
+ * {@link Logger} adapter over a Pino-shaped logger instance. Construct it
+ * directly when you already have a configured Pino logger, or use
+ * {@link createPinoLogger} to build one with the optional `pino` /
+ * `pino-pretty` dependencies.
+ */
 export declare class PinoLogger implements Logger {
     readonly level: LogLevel;
     private readonly logger;
+    /**
+     * @param logger Pino-compatible underlying logger.
+     * @param level  Minimum level to emit (also forwarded to `logger.level`).
+     */
     constructor(logger: PinoLikeLogger, level?: LogLevel);
+    /** Emits a `trace` record. */
     trace(message: string, context?: Readonly<Record<string, unknown>>): void;
+    /** Emits a `debug` record. */
     debug(message: string, context?: Readonly<Record<string, unknown>>): void;
+    /** Emits an `info` record. */
     info(message: string, context?: Readonly<Record<string, unknown>>): void;
+    /** Emits a `warn` record. */
     warn(message: string, context?: Readonly<Record<string, unknown>>): void;
+    /** Emits an `error` record. */
     error(message: string, context?: Readonly<Record<string, unknown>>): void;
+    /**
+     * Returns a derived logger that pre-binds `bindings` into every log
+     * call's context. Delegates to the underlying pino `child()` when
+     * available; otherwise wraps with a parent + bindings merge.
+     */
+    child(bindings: Readonly<Record<string, unknown>>): Logger;
     private write;
 }
+/**
+ * Dynamically loads `pino` (and optionally `pino-pretty` when `pretty` is set),
+ * configures it with the given options, and wraps it in a {@link PinoLogger}.
+ * Throws if the optional `pino` dependency is not installed.
+ */
 export declare function createPinoLogger(options?: PinoLoggerOptions): Promise<PinoLogger>;
 export {};

package/dist/types/infra/log/types.d.ts

@@ -6,5 +6,11 @@ export interface Logger {
     info(message: string, context?: Readonly<Record<string, unknown>>): void;
     warn(message: string, context?: Readonly<Record<string, unknown>>): void;
     error(message: string, context?: Readonly<Record<string, unknown>>): void;
+    /**
+     * Returns a derived logger that pre-binds `bindings` into every log
+     * call's context object. Bindings stack: `parent.child(a).child(b)`
+     * merges `{ ...a, ...b }`. Per-call context wins on key conflicts.
+     */
+    child(bindings: Readonly<Record<string, unknown>>): Logger;
 }
 export declare function createNoopLogger(level?: LogLevel): Logger;

package/dist/types/infra/perf/BackgroundQueue.d.ts

@@ -6,6 +6,22 @@ export interface BackgroundQueueOptions<K extends string, V> {
     readonly onError?: (key: K, error: unknown, attempt: number) => void;
     readonly onPressure?: (pendingKeys: number) => void;
     readonly onDiscard?: (key: K, value: V) => void;
+    /**
+     * Optional bulk writer. When set, the drain loop coalesces up to
+     * {@link maxBatchSize} pending entries into a single
+     * `batchWriter([...])` call instead of issuing
+     * {@link maxWriteConcurrency} parallel `writer(key, value)` calls.
+     *
+     * Failure semantics: the batch is retried as a unit. The store-side
+     * implementation should be idempotent (upsert) so a partial-success +
+     * retry does not corrupt state.
+     */
+    readonly batchWriter?: (entries: ReadonlyArray<{
+        readonly key: K;
+        readonly value: V;
+    }>) => Promise<void>;
+    /** Max entries per `batchWriter` call. Default 250. Ignored without `batchWriter`. */
+    readonly maxBatchSize?: number;
 }
 export interface BackgroundQueueFlushResult {
     readonly flushed: number;
@@ -13,6 +29,8 @@ export interface BackgroundQueueFlushResult {
 }
 export declare class BackgroundQueue<K extends string, V> {
     private readonly writer;
+    private readonly batchWriter;
+    private readonly maxBatchSize;
     private readonly coalesce;
     private readonly maxPendingKeys;
     private readonly maxWriteConcurrency;
@@ -39,6 +57,7 @@ export declare class BackgroundQueue<K extends string, V> {
     private ensureDrain;
     private drainLoop;
     private takeBatch;
+    private processBatch;
     private processEntry;
     private takeNext;
     private mergeForRetry;

package/dist/types/infra/perf/StoreLock.d.ts

@@ -1,5 +1,6 @@
 type StoreTask<T> = () => Promise<T>;
 export declare class StoreLock {
+    private static readonly _noop;
     private readonly chains;
     private closed;
     run<T>(key: string, task: StoreTask<T>): Promise<T>;

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

@@ -1,10 +1,17 @@
 export declare const DEFAULT_MEDIA_HOSTS: readonly ["mmg.whatsapp.net", "mmg-fallback.whatsapp.net"];
 export declare const MEDIA_CONN_CACHE_GRACE_MS = 30000;
-export declare const MEDIA_HKDF_SIZE = 112;
+export declare const MEDIA_HKDF_SIZE = 80;
 export declare const IV_SIZE = 16;
 export declare const ENC_KEY_START = 16;
 export declare const ENC_KEY_END = 48;
 export declare const MAC_KEY_START = 48;
 export declare const MAC_KEY_END = 80;
 export declare const HMAC_TRUNCATED_SIZE = 10;
-export declare const MEDIA_UPLOAD_PATHS: Readonly<Record<'image' | 'video' | 'audio' | 'document' | 'sticker' | 'gif' | 'ptt' | 'ptv', string>>;
+export declare const SIDECAR_CHUNK_SIZE = 65536;
+export declare const SIDECAR_HMAC_SIZE = 10;
+export type MediaUploadKind = 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'gif' | 'ptt' | 'ptv' | 'ads-image' | 'ads-video' | 'group-history' | 'md-app-state' | 'md-msg-hist' | 'music-artwork' | 'newsletter-music-artwork' | 'sticker-pack' | 'thumbnail-document' | 'thumbnail-image' | 'thumbnail-link' | 'thumbnail-sticker-pack' | 'thumbnail-video' | 'waffle-image' | 'waffle-video';
+export declare const MEDIA_UPLOAD_PATHS: Readonly<Record<MediaUploadKind, string>>;
+export type NewsletterMediaKind = 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'sticker-pack' | 'gif' | 'ptt' | 'ptv' | 'thumbnail-link';
+export type PpsUploadKind = 'photo' | 'biz-cover-photo';
+export declare const PPS_UPLOAD_PATHS: Readonly<Record<PpsUploadKind, string>>;
+export declare const NEWSLETTER_MEDIA_UPLOAD_PATHS: Readonly<Record<NewsletterMediaKind, string>>;

package/dist/types/media/crypto/WaMediaCrypto.d.ts

@@ -0,0 +1,59 @@
+import { type Readable } from 'node:stream';
+import type { MediaCryptoType, WaMediaDecryptionResult, WaMediaDecryptReadableOptions, WaMediaDerivedKeys, WaMediaEncryptionResult, WaMediaFileEncryptionResult, WaMediaReadableDecryptionResult, WaMediaReadableEncryptionResult } from '../types';
+/**
+ * WhatsApp media payload encryption/decryption (AES-256-CBC + HMAC-SHA-256 +
+ * SHA-256 hashes + streaming sidecar). Buffer-only and streaming variants are
+ * provided for upload, download, and disk-staged encryption.
+ */
+export declare class WaMediaCrypto {
+    /** Generates a fresh 32-byte media key suitable for {@link deriveKeys}. */
+    static generateMediaKey(): Promise<Uint8Array>;
+    /**
+     * Derives the per-type AES IV, AES key, and MAC key from `mediaKey` using
+     * HKDF with the {@link getWaMediaHkdfInfo} context.
+     */
+    static deriveKeys(mediaType: MediaCryptoType, mediaKey: Uint8Array): WaMediaDerivedKeys;
+    /**
+     * Encrypts an in-memory buffer with the streaming sidecar (unless disabled)
+     * and an optional first-frame sidecar for instant-thumbnail playback.
+     */
+    static encryptBytes(mediaType: MediaCryptoType, mediaKey: Uint8Array, plaintext: Uint8Array, options?: {
+        readonly sidecar?: boolean;
+        readonly firstFrameLength?: number;
+    }): Promise<WaMediaEncryptionResult>;
+    /**
+     * Decrypts an in-memory `ciphertext||mac` buffer. Verifies the encrypted
+     * SHA-256, the MAC, and (when supplied) the plaintext SHA-256. Pass
+     * `skipMacVerification` only when the MAC was checked elsewhere.
+     */
+    static decryptBytes(mediaType: MediaCryptoType, mediaKey: Uint8Array, ciphertextHmac: Uint8Array, expectedFileSha256?: Uint8Array, expectedFileEncSha256?: Uint8Array, skipMacVerification?: boolean): Promise<WaMediaDecryptionResult>;
+    /**
+     * Streaming encrypt – returns an `encrypted` Readable plus a `metadata`
+     * promise that resolves with hashes/sidecars after the stream ends.
+     */
+    static encryptReadable(mediaType: MediaCryptoType, mediaKey: Uint8Array, plaintext: Readable, options?: {
+        readonly sidecar?: boolean;
+        readonly firstFrameLength?: number;
+        readonly expectedFileSize?: number;
+    }): Promise<WaMediaReadableEncryptionResult>;
+    /**
+     * Encrypts `plaintext` to a temporary file in `tmpdir()` and returns its
+     * path/size/hashes. The file is removed on failure; call
+     * {@link cleanupEncryptedFile} after a successful upload.
+     */
+    static encryptToFile(mediaType: MediaCryptoType, mediaKey: Uint8Array, plaintext: Readable, options?: {
+        readonly sidecar?: boolean;
+        readonly firstFrameLength?: number;
+        readonly expectedFileSize?: number;
+    }): Promise<WaMediaFileEncryptionResult>;
+    /** Removes a temporary file produced by {@link encryptToFile}; missing files are ignored. */
+    static cleanupEncryptedFile(filePath: string): Promise<void>;
+    /**
+     * Streaming decrypt – returns a `plaintext` Readable plus a `metadata`
+     * promise that resolves with the verified hashes after the stream ends
+     * (or rejects on MAC/hash failure).
+     */
+    static decryptReadable(encrypted: Readable, options: WaMediaDecryptReadableOptions): Promise<WaMediaReadableDecryptionResult>;
+    /** Returns the ciphertext byte length (AES-CBC padded + 10-byte MAC) for a given plaintext size. */
+    static encryptedLength(plaintextLength: number): number;
+}

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

@@ -1,4 +1,7 @@
-export { WaMediaTransferClient } from './WaMediaTransferClient';
-export { parseMediaConnResponse } from './conn';
-export type { WaMediaConn } from './types';
-export { WaMediaCrypto } from './WaMediaCrypto';
+export { WaMediaTransferClient } from './transfer/WaMediaTransferClient';
+export { parseMediaConnResponse } from './transfer/conn';
+export { DEFAULT_MEDIA_HOSTS, MEDIA_UPLOAD_PATHS, NEWSLETTER_MEDIA_UPLOAD_PATHS, PPS_UPLOAD_PATHS } from './constants';
+export type { MediaUploadKind, NewsletterMediaKind, PpsUploadKind } from './constants';
+export type { MediaCryptoType, MediaKind, WaMediaConn } from './types';
+export { WaMediaCrypto } from './crypto/WaMediaCrypto';
+export type { WaMediaProcessor, WaMediaProcessorCallContext, WaMediaProcessorImageResult, WaMediaProcessorInput, WaMediaProcessorProbeResult, WaMediaProcessorStickerThumbnailResult, WaMediaProcessorWaveformResult } from './processor';

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

@@ -0,0 +1,50 @@
+import type { Readable } from 'node:stream';
+import type { Logger } from '../infra/log/types';
+export interface WaMediaProcessorImageResult {
+    readonly jpegThumbnail: Uint8Array;
+    readonly width: number;
+    readonly height: number;
+}
+export interface WaMediaProcessorStickerThumbnailResult {
+    readonly pngThumbnail: Uint8Array;
+    readonly width: number;
+    readonly height: number;
+}
+export interface WaMediaProcessorProbeResult {
+    readonly durationSeconds?: number;
+    readonly width?: number;
+    readonly height?: number;
+}
+export interface WaMediaProcessorWaveformResult {
+    readonly waveform: Uint8Array;
+    readonly durationSeconds: number;
+}
+export type WaMediaProcessorInput = Uint8Array | Readable | string;
+/**
+ * Per-call context the runtime passes to every {@link WaMediaProcessor}
+ * method. Currently carries an optional `logger` so the processor can
+ * emit warnings (missing binary, probe failure, ...) through the same
+ * `Logger` the caller is using - including any session/scope bindings
+ * the caller has already attached. The processor must stay stateless
+ * with respect to the logger: a single processor instance shared across
+ * multiple `WaClient` sessions receives a different `ctx.logger` per
+ * call and must not cache it.
+ */
+export interface WaMediaProcessorCallContext {
+    readonly logger?: Logger;
+}
+export interface WaMediaProcessor {
+    readonly generateImageThumbnail?: (input: WaMediaProcessorInput, maxEdge: number, ctx?: WaMediaProcessorCallContext) => Promise<WaMediaProcessorImageResult>;
+    readonly generateVideoThumbnail?: (input: WaMediaProcessorInput, maxEdge: number, ctx?: WaMediaProcessorCallContext) => Promise<WaMediaProcessorImageResult | null>;
+    readonly probeMedia?: (input: WaMediaProcessorInput, ctx?: WaMediaProcessorCallContext) => Promise<WaMediaProcessorProbeResult>;
+    readonly computeWaveform?: (input: WaMediaProcessorInput, ctx?: WaMediaProcessorCallContext) => Promise<WaMediaProcessorWaveformResult | null>;
+    readonly normalizeVoiceNote?: (input: WaMediaProcessorInput, ctx?: WaMediaProcessorCallContext) => Promise<Readable | null>;
+    readonly generateStickerThumbnail?: (input: WaMediaProcessorInput, maxEdge: number, ctx?: WaMediaProcessorCallContext) => Promise<WaMediaProcessorStickerThumbnailResult>;
+    /**
+     * Infers the input's mime type (e.g. via magic-byte sniffing). Accepts the
+     * resolved on-disk shape: a path or a buffer; the message builder always
+     * stages streams to a temp file before calling this. Returns `null` when
+     * the type can't be determined.
+     */
+    readonly detectMimetype?: (input: string | Uint8Array, ctx?: WaMediaProcessorCallContext) => Promise<string | null>;
+}

package/dist/types/media/sticker/sticker-pack.d.ts

@@ -0,0 +1,6 @@
+import { Readable } from 'node:stream';
+export interface StickerPackZipEntry {
+    readonly fileName: string;
+    readonly source: Uint8Array | string;
+}
+export declare function createStickerPackZipStream(entries: readonly StickerPackZipEntry[]): Readable;