zapo-js 0.1.2 → 0.3.0

package/dist/types/client/types.d.ts

@@ -1,7 +1,10 @@
 import type { AppStateCollectionName } from '../appstate/types';
-import type { WaAuthClientOptions, WaAuthCredentials, WaAuthSocketOptions } from '../auth/types';
+import type { WaAuthClientOptions, WaAuthCredentials, WaAuthDangerousOptions, WaAuthSocketOptions } from '../auth/types';
+import type { WaMediaProcessor } from '../media/processor';
+import type { WaDecodedAddon } from '../message/addon-crypto';
 import type { WaMessagePublishOptions } from '../message/types';
 import type { Proto } from '..';
+import type { WaConnectionCode, WaConnectionOpenReason, WaDisconnectReason } from '../protocol/stream';
 import type { WaStore } from '../store/types';
 import type { BinaryNode, WaProxyTransport } from '../transport/types';
 export interface WaClientProxyOptions {
@@ -9,6 +12,23 @@ export interface WaClientProxyOptions {
     readonly mediaUpload?: WaProxyTransport;
     readonly mediaDownload?: WaProxyTransport;
 }
+export interface WaLogoutStoreClearOptions {
+    readonly auth?: boolean;
+    readonly signal?: boolean;
+    readonly preKey?: boolean;
+    readonly session?: boolean;
+    readonly identity?: boolean;
+    readonly senderKey?: boolean;
+    readonly appState?: boolean;
+    readonly retry?: boolean;
+    readonly participants?: boolean;
+    readonly deviceList?: boolean;
+    readonly messages?: boolean;
+    readonly messageSecret?: boolean;
+    readonly threads?: boolean;
+    readonly contacts?: boolean;
+    readonly privacyToken?: boolean;
+}
 export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOptions {
     readonly store: WaStore;
     readonly sessionId: string;
@@ -24,10 +44,88 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
     readonly messageAckTimeoutMs?: number;
     readonly messageMaxAttempts?: number;
     readonly messageRetryDelayMs?: number;
+    readonly writeBehind?: WaWriteBehindOptions;
     readonly history?: WaHistorySyncOptions;
     readonly chatEvents?: {
         readonly emitSnapshotMutations?: boolean;
     };
+    readonly privacyToken?: WaPrivacyTokenOptions;
+    readonly addons?: WaAddonOptions;
+    readonly logoutStoreClear?: WaLogoutStoreClearOptions;
+    readonly media?: WaMediaOptions;
+    /**
+     * Test-only overrides intended for running against a fake server.
+     *
+     * These hooks **do not** bypass any security checks — they only swap in
+     * test fixtures (e.g. a different root CA) so the full verification code
+     * path still runs end-to-end. If you actually need to skip a check, use
+     * `dangerous` instead.
+     */
+    readonly testHooks?: WaClientTestHooks;
+    /**
+     * Dangerous escape hatches. **Do not enable in production.** Each flag here
+     * disables a security check the production code path enforces.
+     */
+    readonly dangerous?: WaClientDangerousOptions;
+}
+export interface WaClientDangerousOptions extends WaAuthDangerousOptions {
+    /**
+     * Skip the XEdDSA signature check on incoming group sender-key messages.
+     * Ciphertexts will be decrypted even if the trailing signature does not
+     * verify against the stored sender signing public key.
+     */
+    readonly disableSenderKeySignatureVerification?: boolean;
+    /**
+     * Skip HMAC verification across the app-state sync pipeline: per-mutation
+     * value and index MACs, snapshot MACs, and patch MACs. Tampered server
+     * payloads will be accepted as long as the ciphertext decrypts cleanly.
+     */
+    readonly disableAppStateMacVerification?: boolean;
+    /**
+     * Skip the truncated HMAC-SHA256 check on encrypted media payloads
+     * during download. Tampered ciphertexts will still be decrypted.
+     */
+    readonly disableMediaMacVerification?: boolean;
+}
+export interface WaClientTestHooks {
+    /**
+     * Override the noise certificate-chain root CA used to verify the
+     * server's static key during the handshake.
+     *
+     * The default is the production WhatsApp root. Tests against a fake
+     * server inject the fake server's ephemeral root here so that the lib
+     * still runs the full certificate-verification code path against a
+     * chain signed by a known key — no validation logic is bypassed.
+     */
+    readonly noiseRootCa?: WaNoiseRootCaOverride;
+}
+export interface WaNoiseRootCaOverride {
+    /** Serialized X25519 public key (32 bytes raw, no version prefix). */
+    readonly publicKey: Uint8Array;
+    /** Serial number that intermediate certificates issued by this root must declare. */
+    readonly serial: number;
+}
+export interface WaMediaOptions {
+    readonly processor?: WaMediaProcessor;
+    readonly generateThumbnail?: boolean;
+    readonly generateProbe?: boolean;
+    readonly generateWaveform?: boolean;
+    readonly generateStickerThumbnail?: boolean;
+}
+export interface WaAddonOptions {
+    readonly autoDecrypt?: boolean;
+}
+export interface WaPrivacyTokenOptions {
+    readonly tcTokenDurationS?: number;
+    readonly tcTokenNumBuckets?: number;
+    readonly tcTokenSenderDurationS?: number;
+    readonly tcTokenSenderNumBuckets?: number;
+    readonly tcTokenMaxDurationS?: number;
+}
+export interface WaWriteBehindOptions {
+    readonly maxPendingKeys?: number;
+    readonly maxWriteConcurrency?: number;
+    readonly flushTimeoutMs?: number;
 }
 export interface WaHistorySyncOptions {
     readonly enabled?: boolean;
@@ -47,6 +145,7 @@ export interface WaSignalMessagePublishInput {
 export interface WaSendMessageOptions extends WaMessagePublishOptions {
     readonly id?: string;
     readonly expectedIdentity?: Uint8Array;
+    readonly subtype?: string;
 }
 export interface WaClearChatOptions {
     readonly deleteStarred?: boolean;
@@ -106,6 +205,26 @@ export interface WaIncomingNotificationEvent extends WaIncomingBaseEvent {
     readonly classification?: 'core' | 'out_of_scope' | 'unknown' | 'info_bulletin';
     readonly details?: Readonly<Record<string, unknown>>;
 }
+export interface WaRegistrationCodeEvent extends WaIncomingBaseEvent {
+    readonly code: string;
+    readonly expiryTimestampMs: number;
+    readonly fromDeviceId: string;
+}
+export interface WaAccountTakeoverNoticeEvent extends WaIncomingBaseEvent {
+    readonly serverToken: string;
+    readonly attemptTimestampMs: number;
+    readonly newDeviceName?: string;
+    readonly newDevicePlatform?: string;
+    readonly newDeviceAppVersion?: string;
+}
+export type WaAddonKind = 'reaction' | 'poll_vote' | 'event_response' | 'comment';
+export interface WaIncomingAddonEvent extends WaIncomingBaseEvent {
+    readonly kind: WaAddonKind;
+    readonly targetMessageId: string;
+    readonly senderJid: string;
+    readonly decrypted: WaDecodedAddon;
+    readonly raw: Proto.IMessage;
+}
 export interface WaIncomingFailureEvent extends WaIncomingBaseEvent {
     readonly failureReason?: number;
     readonly failureCode?: number;
@@ -201,7 +320,19 @@ export interface WaChatEvent {
     readonly locked?: boolean;
     readonly deviceAgentId?: string;
 }
-export type WaEmptyEvent = Readonly<Record<string, never>>;
+export type WaConnectionEvent = {
+    readonly status: 'open';
+    readonly reason: WaConnectionOpenReason;
+    readonly code: null;
+    readonly isLogout: false;
+    readonly isNewLogin: boolean;
+} | {
+    readonly status: 'close';
+    readonly reason: WaDisconnectReason;
+    readonly code: WaConnectionCode | null;
+    readonly isLogout: boolean;
+    readonly isNewLogin: false;
+};
 export interface WaClientEventMap {
     readonly auth_qr: (event: {
         readonly qr: string;
@@ -222,8 +353,7 @@ export interface WaClientEventMap {
     readonly client_error: (event: {
         readonly error: Error;
     }) => void;
-    readonly connection_open: (event: WaEmptyEvent) => void;
-    readonly connection_close: (event: WaEmptyEvent) => void;
+    readonly connection: (event: WaConnectionEvent) => void;
     readonly transport_frame_in: (event: {
         readonly frame: Uint8Array;
     }) => void;
@@ -243,16 +373,33 @@ export interface WaClientEventMap {
         readonly frame: Uint8Array;
     }) => void;
     readonly message: (event: WaIncomingMessageEvent) => void;
+    readonly message_addon: (event: WaIncomingAddonEvent) => void;
     readonly message_protocol: (event: WaIncomingProtocolMessageEvent) => void;
     readonly message_receipt: (event: WaIncomingReceiptEvent) => void;
     readonly presence: (event: WaIncomingPresenceEvent) => void;
     readonly chatstate: (event: WaIncomingChatstateEvent) => void;
     readonly call: (event: WaIncomingCallEvent) => void;
     readonly notification: (event: WaIncomingNotificationEvent) => void;
+    readonly registration_code_received: (event: WaRegistrationCodeEvent) => void;
+    readonly account_takeover_notice: (event: WaAccountTakeoverNoticeEvent) => void;
     readonly failure: (event: WaIncomingFailureEvent) => void;
     readonly stanza_error: (event: WaIncomingBaseEvent) => void;
     readonly stanza_unhandled: (event: WaIncomingUnhandledStanzaEvent) => void;
     readonly group_event: (event: WaGroupEvent) => void;
     readonly chat_event: (event: WaChatEvent) => void;
     readonly history_sync_chunk: (event: WaHistorySyncChunkEvent) => void;
+    readonly privacy_token_update: (event: WaPrivacyTokenUpdateEvent) => void;
+    readonly offline_resume: (event: WaOfflineResumeEvent) => void;
+}
+export interface WaOfflineResumeEvent {
+    readonly status: 'resuming' | 'complete';
+    readonly totalStanzas: number;
+    readonly remainingStanzas: number;
+    readonly forced: boolean;
+}
+export interface WaPrivacyTokenUpdateEvent {
+    readonly jid: string;
+    readonly timestampS: number;
+    readonly type: string;
+    readonly source: 'notification' | 'history_sync';
 }

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

@@ -6,5 +6,6 @@ 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 { randomBytesAsync, randomIntAsync } from '../core/random';
-export { type CryptoKey, sha1, sha256, sha512, importAesGcmKey, aesGcmEncrypt, aesGcmDecrypt, importAesCbcKey, aesCbcEncrypt, aesCbcDecrypt, importHmacKey, importHmacSha512Key, hmacSign, pbkdf2DeriveAesCtrKey, aesCtrEncrypt, aesCtrDecrypt, ed25519VerifyRaw } from '../core/primitives';
+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 { xeddsaSign, xeddsaVerify } from '../core/xeddsa';

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

@@ -1,5 +1,7 @@
 /**
  * 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.
  */
 export declare function buildNonce(counter: number): Uint8Array;

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

@@ -9,7 +9,7 @@ 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 md5Bytes(input: string | Uint8Array): 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>;
@@ -22,4 +22,3 @@ export declare function hmacSign(key: webcrypto.CryptoKey, data: Uint8Array): Pr
 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 ed25519VerifyRaw(publicKey: Uint8Array, signature: Uint8Array, message: Uint8Array): Promise<boolean>;

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

@@ -1,2 +1,3 @@
-export declare function randomBytesAsync(size: number): Promise<Uint8Array>;
+export declare function randomFillAsync(target: Uint8Array, offset?: number, size?: number): Promise<Uint8Array>;
 export declare const randomIntAsync: (min: number, max: number) => Promise<number>;
+export declare const randomBytesAsync: (size: number) => Promise<Uint8Array>;

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

@@ -0,0 +1,2 @@
+export declare function xeddsaVerify(curvePublicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): Promise<boolean>;
+export declare function xeddsaSign(privateKey: Uint8Array, message: Uint8Array): Promise<Uint8Array>;

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

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

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

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

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

@@ -1,7 +1,9 @@
+import { type Fe } from '../math/fe';
 import type { ExtendedPoint } from '../math/types';
 export declare const FIELD_P: bigint;
 export declare const GROUP_L: bigint;
-export declare const EDWARDS_D: bigint;
-export declare const TWO_D: 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/fe.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Field element arithmetic for GF(2^255-19).
+ * Representation: 16 limbs of 16 bits in Float64Array (tweetnacl style).
+ * Hot-path operations are allocation-free using pre-allocated temporaries.
+ */
+export type Fe = Float64Array;
+export declare function fe(): Fe;
+export declare function feCopy(o: Fe, a: Fe): void;
+export declare function feFromBigInt(n: bigint): Fe;
+export declare function feToBigInt(a: Fe): bigint;
+export declare function feFromBytes(o: Fe, s: Uint8Array): void;
+export declare function fePack(o: Uint8Array, n: Fe): void;
+export declare function feAdd(o: Fe, a: Fe, b: Fe): void;
+export declare function feSub(o: Fe, a: Fe, b: Fe): void;
+export declare function feNeg(o: Fe, a: Fe): void;
+/**
+ * Fully unrolled field multiplication with folded reduction.
+ * Computes o = a * b mod (2^255-19) using negacyclic convolution:
+ * t[i] = Σ a[j]*b[i-j] (direct) + 38 * Σ a[j]*b[i+16-j] (wrapped)
+ * All values in local variables for register allocation.
+ */
+export declare function feMul(o: Fe, a: Fe, b: Fe): void;
+/**
+ * Fully unrolled field squaring with folded reduction and symmetry.
+ * Exploits a[j]*a[k] == a[k]*a[j] to halve off-diagonal multiplications.
+ * Combined with negacyclic reduction: wrapped terms use a38[k] = 38*a[k].
+ */
+export declare function feSqr(o: Fe, a: Fe): void;
+export declare function feSqrN(o: Fe, a: Fe, n: number): void;
+export declare function feInv(o: Fe, a: Fe): void;

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

@@ -1,5 +1,3 @@
-import { FIELD_P, GROUP_L } from '../math/constants';
-export { FIELD_P, GROUP_L };
 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/crypto/math/types.d.ts

@@ -1,6 +1,13 @@
+import type { Fe } from '../math/fe';
 export interface ExtendedPoint {
-    readonly x: bigint;
-    readonly y: bigint;
-    readonly z: bigint;
-    readonly t: bigint;
+    readonly x: Fe;
+    readonly y: Fe;
+    readonly z: Fe;
+    readonly t: Fe;
+}
+export interface MutablePoint {
+    x: Fe;
+    y: Fe;
+    z: Fe;
+    t: Fe;
 }

package/dist/types/index.d.ts

@@ -1,10 +1,13 @@
 export { WaClient } from '@client';
-export type { WaClientEventMap, WaClientOptions, WaClientProxyOptions, WaHistorySyncChunkEvent, WaHistorySyncOptions } from '@client';
+export type { WaClientEventMap, WaClientOptions, WaClientProxyOptions, WaHistorySyncChunkEvent, WaHistorySyncOptions, WaWriteBehindOptions } from '@client';
+export type { WaBlocklistResult, WaPrivacyCoordinator, WaPrivacyDisallowedListResult, WaPrivacySettings } from './client/coordinators/WaPrivacyCoordinator';
+export type { WaAuthCredentials } from './auth/types';
 export { ConsoleLogger } from './infra/log/ConsoleLogger';
 export { PinoLogger, createPinoLogger } from './infra/log/PinoLogger';
 export type { PinoLoggerOptions } from './infra/log/PinoLogger';
 export type { Logger, LogLevel } from './infra/log/types';
 export { createStore } from '@store';
-export type { WaAppStateCollectionStoreState, WaAppStateStore, WaAuthStore, WaContactStore, WaCreateStoreCustomCacheProviders, WaCreateStoreCustomProviders, WaCreateStoreOptions, WaDeviceListSnapshot, WaDeviceListStore, WaMessageStore, WaParticipantsSnapshot, WaParticipantsStore, WaRetryStore, WaSenderKeyStore, WaSignalStore, WaSqliteDriver, WaSqliteStorageOptions, WaStoredContactRecord, WaStoredMessageRecord, WaStoredThreadRecord, WaStore, WaStoreCacheProviderSelection, WaStoreCacheTtlSelection, WaStoreDomainValueOrFactory, WaStoreProviderSelection, 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_XMLNS } from '@protocol';
+export type { WaAppStateCollectionStoreState, WaAppStateStore, WaAuthStore, WaContactStore, WaCreateStoreOptions, WaDeviceListSnapshot, WaDeviceListStore, WaMessageStore, WaParticipantsSnapshot, WaParticipantsStore, WaRetryStore, WaSenderKeyStore, WaSessionStore, WaSignalStore, WaIdentityStore, WaPreKeyStore, 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 { proto } from '.';

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

@@ -1,4 +1,4 @@
-import type { LogLevel, Logger } from '../log/types';
+import type { Logger, LogLevel } from '../log/types';
 export declare class ConsoleLogger implements Logger {
     readonly level: LogLevel;
     private readonly minLevelPriority;

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;

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

@@ -0,0 +1,58 @@
+export interface BackgroundQueueOptions<K extends string, V> {
+    readonly coalesce?: (previous: V, incoming: V, key: K) => V;
+    readonly maxPendingKeys?: number;
+    readonly maxWriteConcurrency?: number;
+    readonly flushTimeoutMs?: number;
+    readonly onError?: (key: K, error: unknown, attempt: number) => void;
+    readonly onPressure?: (pendingKeys: number) => void;
+    readonly onDiscard?: (key: K, value: V) => void;
+}
+export interface BackgroundQueueFlushResult {
+    readonly flushed: number;
+    readonly remaining: number;
+}
+export declare class BackgroundQueue<K extends string, V> {
+    private readonly writer;
+    private readonly coalesce;
+    private readonly maxPendingKeys;
+    private readonly maxWriteConcurrency;
+    private readonly flushTimeoutMs;
+    private readonly onError?;
+    private readonly onPressure?;
+    private readonly onDiscard?;
+    private readonly pendingByKey;
+    private readonly retryTimersByKey;
+    private readonly stateWaiters;
+    private drainingPromise;
+    private inFlight;
+    private flushedCount;
+    private shutdownRequested;
+    private retryDisabled;
+    constructor(writer: (key: K, value: V) => Promise<void>, options?: BackgroundQueueOptions<K, V>);
+    enqueue(key: K, value: V): void;
+    enqueueAsync(key: K, value: V): Promise<void>;
+    private waitForCapacity;
+    private addPendingEntry;
+    private detachRetryEntry;
+    flush(timeoutMs?: number): Promise<BackgroundQueueFlushResult>;
+    destroy(timeoutMs?: number): Promise<BackgroundQueueFlushResult>;
+    private ensureDrain;
+    private drainLoop;
+    private takeBatch;
+    private processEntry;
+    private takeNext;
+    private mergeForRetry;
+    private retryDelayMs;
+    private scheduleRetry;
+    private resolveEntry;
+    private discardEntry;
+    private discardPending;
+    private remaining;
+    private trackedKeys;
+    private notifyStateChange;
+    private waitForStateChange;
+    private removeStateWaiter;
+    private invokeOnError;
+    private invokeOnPressure;
+    private invokeOnDiscard;
+}

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

@@ -0,0 +1,4 @@
+export declare class PromiseDedup {
+    private readonly inFlight;
+    run<T>(key: string, task: () => Promise<T>): Promise<T>;
+}

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

@@ -0,0 +1,17 @@
+type SharedExclusiveTask<T> = () => Promise<T>;
+export declare class SharedExclusiveGate {
+    private activeShared;
+    private pendingExclusive;
+    private exclusiveActive;
+    private closed;
+    private readonly waiters;
+    runShared<T>(task: SharedExclusiveTask<T>): Promise<T>;
+    private runSharedSlow;
+    runExclusive<T>(task: SharedExclusiveTask<T>): Promise<T>;
+    close(): Promise<void>;
+    private acquireShared;
+    private acquireExclusive;
+    private notifyStateChange;
+    private waitForStateChange;
+}
+export {};

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

@@ -0,0 +1,11 @@
+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>;
+    private runInternal;
+    runMany<T>(keys: readonly string[], task: StoreTask<T>): Promise<T>;
+    shutdown(): Promise<void>;
+}
+export {};

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

@@ -1,12 +1,22 @@
-import type { Readable } from 'node:stream';
-import type { MediaCryptoType, WaMediaDecryptReadableOptions, WaMediaDecryptionResult, WaMediaDerivedKeys, WaMediaEncryptionResult, WaMediaReadableDecryptionResult, WaMediaReadableEncryptionResult } from './types';
+import { type Readable } from 'node:stream';
+import type { MediaCryptoType, WaMediaDecryptionResult, WaMediaDecryptReadableOptions, WaMediaDerivedKeys, WaMediaEncryptionResult, WaMediaFileEncryptionResult, WaMediaReadableDecryptionResult, WaMediaReadableEncryptionResult } from './types';
 export declare class WaMediaCrypto {
     static generateMediaKey(): Promise<Uint8Array>;
     static deriveKeys(mediaType: MediaCryptoType, mediaKey: Uint8Array): Promise<WaMediaDerivedKeys>;
-    static encryptBytes(mediaType: MediaCryptoType, mediaKey: Uint8Array, plaintext: Uint8Array): Promise<WaMediaEncryptionResult>;
-    static decryptBytes(mediaType: MediaCryptoType, mediaKey: Uint8Array, ciphertextHmac: Uint8Array, expectedFileSha256?: Uint8Array, expectedFileEncSha256?: Uint8Array): Promise<WaMediaDecryptionResult>;
-    static encryptReadable(mediaType: MediaCryptoType, mediaKey: Uint8Array, plaintext: Readable): Promise<WaMediaReadableEncryptionResult>;
-    static decryptReadableToBytes(encrypted: Readable, options: WaMediaDecryptReadableOptions): Promise<WaMediaDecryptionResult>;
+    static encryptBytes(mediaType: MediaCryptoType, mediaKey: Uint8Array, plaintext: Uint8Array, options?: {
+        readonly sidecar?: boolean;
+        readonly firstFrameLength?: number;
+    }): Promise<WaMediaEncryptionResult>;
+    static decryptBytes(mediaType: MediaCryptoType, mediaKey: Uint8Array, ciphertextHmac: Uint8Array, expectedFileSha256?: Uint8Array, expectedFileEncSha256?: Uint8Array, skipMacVerification?: boolean): Promise<WaMediaDecryptionResult>;
+    static encryptReadable(mediaType: MediaCryptoType, mediaKey: Uint8Array, plaintext: Readable, options?: {
+        readonly sidecar?: boolean;
+        readonly firstFrameLength?: number;
+    }): Promise<WaMediaReadableEncryptionResult>;
+    static encryptToFile(mediaType: MediaCryptoType, mediaKey: Uint8Array, plaintext: Readable, options?: {
+        readonly sidecar?: boolean;
+        readonly firstFrameLength?: number;
+    }): Promise<WaMediaFileEncryptionResult>;
+    static cleanupEncryptedFile(filePath: string): Promise<void>;
     static decryptReadable(encrypted: Readable, options: WaMediaDecryptReadableOptions): Promise<WaMediaReadableDecryptionResult>;
     static encryptedLength(plaintextLength: number): number;
 }

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

@@ -1,11 +1,10 @@
-import { Readable } from 'node:stream';
-import type { MediaCryptoType, WaMediaTransferClientOptions } from './types';
+import type { Readable } from 'node:stream';
+import type { MediaCryptoType, WaMediaReadableDecryptionResult, WaMediaTransferClientOptions } from './types';
 interface StreamDownloadRequest {
     readonly url?: string;
     readonly directPath?: string;
     readonly hosts?: readonly string[];
     readonly headers?: Readonly<Record<string, string>>;
-    readonly dispatcher?: WaMediaTransferClientOptions['defaultDownloadDispatcher'];
     readonly agent?: WaMediaTransferClientOptions['defaultDownloadAgent'];
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
@@ -37,6 +36,7 @@ interface EncryptedUploadResult {
     readonly mediaKey: Uint8Array;
     readonly fileSha256: Uint8Array;
     readonly fileEncSha256: Uint8Array;
+    readonly plaintextLength: number;
 }
 interface EncryptedDownloadRequest extends StreamDownloadRequest {
     readonly mediaType: MediaCryptoType;
@@ -44,48 +44,31 @@ interface EncryptedDownloadRequest extends StreamDownloadRequest {
     readonly fileSha256?: Uint8Array;
     readonly fileEncSha256?: Uint8Array;
 }
-interface EncryptedDownloadStream {
-    readonly plaintext: Readable;
-    readonly metadata: Promise<{
-        readonly fileSha256: Uint8Array;
-        readonly fileEncSha256: Uint8Array;
-    }>;
-}
 export declare class WaMediaTransferClient {
     private readonly logger?;
     private readonly defaultHosts;
     private readonly defaultTimeoutMs;
     private readonly defaultMaxReadBytes;
     private readonly defaultHeaders;
-    private readonly defaultUploadDispatcher;
-    private readonly defaultDownloadDispatcher;
     private readonly defaultUploadAgent;
     private readonly defaultDownloadAgent;
-    private gotModulePromise;
+    private readonly skipMacVerification;
     constructor(options?: WaMediaTransferClientOptions);
     downloadStream(request: StreamDownloadRequest): Promise<StreamTransferResponse>;
     downloadBytes(request: StreamDownloadRequest): Promise<Uint8Array>;
     uploadStream(request: StreamUploadRequest): Promise<StreamTransferResponse>;
     uploadEncrypted(request: EncryptedUploadRequest): Promise<EncryptedUploadResult>;
     downloadAndDecrypt(request: EncryptedDownloadRequest): Promise<Uint8Array>;
-    downloadAndDecryptStream(request: EncryptedDownloadRequest): Promise<EncryptedDownloadStream>;
+    downloadAndDecryptStream(request: EncryptedDownloadRequest): Promise<WaMediaReadableDecryptionResult>;
     readResponseBytes(response: StreamTransferResponse, maxBytes?: number): Promise<Uint8Array>;
-    private transferRequest;
-    private fetchWithDispatcher;
-    private toFetchTransferResponse;
-    private gotWithAgent;
-    private loadGotModule;
-    private toGotTransferResponse;
+    private httpRequest;
     private resolveTransferRequest;
-    private executeTransfer;
     private prepareEncryptedUpload;
     private assertSuccessfulResponse;
     private requireResponseBody;
     private resolveUrls;
-    private readAllBytesWithLimit;
     private fetchWithFallback;
     private createAbortContext;
-    private headersToRecord;
     private drainBody;
 }
 export {};

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

@@ -7,4 +7,6 @@ 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', string>>;
+export declare const SIDECAR_CHUNK_SIZE = 65536;
+export declare const SIDECAR_HMAC_SIZE = 10;
+export declare const MEDIA_UPLOAD_PATHS: Readonly<Record<'image' | 'video' | 'audio' | 'document' | 'sticker' | 'gif' | 'ptt' | 'ptv', string>>;

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

@@ -1,4 +1,5 @@
 export { WaMediaTransferClient } from './WaMediaTransferClient';
 export { parseMediaConnResponse } from './conn';
-export type { WaMediaConn, WaMediaConnHost, WaMediaTransferClientOptions, WaMediaDerivedKeys, WaMediaEncryptionResult, WaMediaDecryptionResult, WaMediaReadableEncryptionResult, WaMediaReadableDecryptionResult } from './types';
+export type { WaMediaConn } from './types';
 export { WaMediaCrypto } from './WaMediaCrypto';
+export type { WaMediaProcessor, WaMediaProcessorImageResult, WaMediaProcessorInput, WaMediaProcessorProbeResult, WaMediaProcessorStickerThumbnailResult, WaMediaProcessorWaveformResult } from './processor';

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

@@ -0,0 +1,28 @@
+import type { Readable } from 'node:stream';
+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;
+export interface WaMediaProcessor {
+    readonly generateImageThumbnail?: (input: WaMediaProcessorInput, maxEdge: number) => Promise<WaMediaProcessorImageResult>;
+    readonly generateVideoThumbnail?: (input: WaMediaProcessorInput, maxEdge: number) => Promise<WaMediaProcessorImageResult | null>;
+    readonly probeMedia?: (input: WaMediaProcessorInput) => Promise<WaMediaProcessorProbeResult>;
+    readonly computeWaveform?: (input: WaMediaProcessorInput) => Promise<WaMediaProcessorWaveformResult | null>;
+    readonly generateStickerThumbnail?: (input: WaMediaProcessorInput, maxEdge: number) => Promise<WaMediaProcessorStickerThumbnailResult>;
+}