zapo-js 1.5.1 → 1.6.1

package/dist/client/WaClient.d.ts

@@ -131,7 +131,7 @@ declare class WaClientImpl extends EventEmitter {
     ignoreKey(input: WaIgnoreKey | WaIgnoreKeyPredicate): () => void;
     /** Auth client: pairing, credentials, registration state. */
     get auth(): WaAuthClient;
-    /** Message coordinator: send/receive, receipts, addons, media download. */
+    /** Message coordinator: send/receive, receipts, addons, media upload/download. */
     get message(): WaMessageCoordinator;
     /** Presence coordinator: own/peer presence subscriptions. */
     get presence(): WaPresenceCoordinator;

package/dist/client/WaClient.js

@@ -414,7 +414,7 @@ class WaClientImpl extends node_events_1.EventEmitter {
     get auth() {
         return this.deps.authClient;
     }
-    /** Message coordinator: send/receive, receipts, addons, media download. */
+    /** Message coordinator: send/receive, receipts, addons, media upload/download. */
     get message() {
         return this.deps.messageCoordinator;
     }

package/dist/client/WaClientFactory.js

@@ -375,7 +375,8 @@ function buildWaClientDependencies(input) {
         logger
     });
     const privacyCoordinator = (0, WaPrivacyCoordinator_1.createPrivacyCoordinator)({
-        queryWithContext: runtime.queryWithContext
+        queryWithContext: runtime.queryWithContext,
+        resolveUserJidPair: (userJid) => signalDeviceSync.resolveUserJidPair(userJid)
     });
     const businessCoordinator = (0, WaBusinessCoordinator_1.createBusinessCoordinator)({
         queryWithContext: runtime.queryWithContext,
@@ -504,6 +505,7 @@ function buildWaClientDependencies(input) {
     const messageCoordinator = new WaMessageCoordinator_1.WaMessageCoordinator({
         messageDispatch,
         mediaTransfer,
+        mediaUploadOptions: mediaMessageBuildOptions,
         logger,
         messageStore: sessionStore.messages,
         messageSecretStore: sessionStore.messageSecret,

package/dist/client/coordinators/WaMessageCoordinator.d.ts

@@ -1,9 +1,12 @@
 import type { Readable } from 'node:stream';
 import type { WaMessageDispatchCoordinator } from '../coordinators/WaMessageDispatchCoordinator';
 import type { WaTrustedContactTokenCoordinator } from '../coordinators/WaTrustedContactTokenCoordinator';
+import { type WaUploadMediaSource } from '../media';
+import { type UploadResult, type WaMediaMessageOptions } from '../messaging/messages';
 import type { WaDownloadMediaOptions, WaIncomingAddonEvent, WaIncomingMessageEvent, WaSendMessageOptions } from '../types';
 import type { Logger } from '../../infra/log/types';
 import type { WaMediaTransferClient } from '../../media/transfer/WaMediaTransferClient';
+import type { MediaKind } from '../../media/types';
 import type { PeerDataOperationRequester } from '../../message/primitives/peer-data-operation';
 import type { WaMessagePublishResult, WaSendMessageContent, WaSendReceiptEventOptions, WaSendReceiptOptions } from '../../message/types';
 import { type Proto } from '../../proto';
@@ -13,6 +16,8 @@ import { type WaMexQuerySocket } from '../../transport/node/mex/client';
 export interface WaMessageCoordinatorDeps {
     readonly messageDispatch: WaMessageDispatchCoordinator;
     readonly mediaTransfer: WaMediaTransferClient;
+    /** Media upload wiring shared with the send path; backs {@link WaMessageCoordinator.upload}. */
+    readonly mediaUploadOptions: WaMediaMessageOptions;
     readonly logger: Logger;
     readonly messageStore: WaMessageStore;
     readonly messageSecretStore: WaMessageSecretStore;
@@ -58,14 +63,47 @@ export interface WaMessageCappingInfo {
     readonly mvStatus: string | null;
     readonly cappingStatus: string | null;
 }
+/**
+ * Media kinds accepted by {@link WaMessageCoordinator.upload}. `gif` is a
+ * GIF-playback video, `ptt` a voice note, `ptv` a round video note.
+ */
+export type WaUploadMediaType = MediaKind | 'gif' | 'ptt';
+/** Options for {@link WaMessageCoordinator.upload}. */
+export interface WaUploadMediaOptions {
+    /** Media type: sets the encryption context and CDN upload path. */
+    readonly type: WaUploadMediaType;
+    /** `Content-Type` for the upload and the mimetype for the message proto. */
+    readonly mimetype?: string;
+    /** Reuse a 32-byte media key instead of generating one. */
+    readonly mediaKey?: Uint8Array;
+    /** Override the streaming sidecar (default on for video/ptv/audio/gif/ptt). */
+    readonly sidecar?: boolean;
+    /** Animated-sticker first-frame length for the first-frame sidecar. */
+    readonly firstFrameLength?: number;
+    /** Per-upload transfer timeout override (ms). */
+    readonly timeoutMs?: number;
+    /** Cancellation signal forwarded to the CDN request. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Reusable descriptor returned by {@link WaMessageCoordinator.upload}: the
+ * {@link UploadResult} fields plus the media-key timestamp and echoed mimetype.
+ */
+export interface WaMediaUploadResult extends UploadResult {
+    /** Unix seconds the media key was minted; belongs on the message proto. */
+    readonly mediaKeyTimestamp: number;
+    /** Echo of the `mimetype` option when provided. */
+    readonly mimetype?: string;
+}
 /**
  * Coordinates outbound message sending, receipts, addon decryption, media
- * download, and the related MEX account queries. Accessed via
+ * upload/download, and the related MEX account queries. Accessed via
  * {@link WaClient.message}.
  */
 export declare class WaMessageCoordinator {
     private readonly messageDispatch;
     private readonly mediaTransfer;
+    private readonly mediaUploadOptions;
     private readonly logger;
     private readonly messageStore;
     private readonly messageSecretStore;
@@ -183,6 +221,36 @@ export declare class WaMessageCoordinator {
      */
     sendReceipt(target: WaIncomingMessageEvent | readonly WaIncomingMessageEvent[], options?: WaSendReceiptEventOptions): Promise<void>;
     sendReceipt(jid: string, ids: string | readonly string[], options?: WaSendReceiptOptions): Promise<void>;
+    /**
+     * Encrypts and uploads standalone media to the WhatsApp CDN and returns the
+     * reusable descriptor, without sending a message - pre-upload once and
+     * reference it across sends, or build custom protos. Needs a connected
+     * session (the host token comes from a `media_conn` IQ). `source` is bytes,
+     * a file path, or a `Readable`. To send the result, spread its fields onto
+     * the matching proto message and pass that to {@link send}.
+     *
+     * @throws when `source` is unsupported, the file is unreadable, or the upload fails.
+     * @example
+     * ```ts
+     * const media = await client.message.upload(await readFile('photo.jpg'), {
+     *     type: 'image',
+     *     mimetype: 'image/jpeg'
+     * })
+     * await client.message.send(jid, {
+     *     imageMessage: {
+     *         url: media.url,
+     *         directPath: media.directPath,
+     *         mediaKey: media.mediaKey,
+     *         fileSha256: media.fileSha256,
+     *         fileEncSha256: media.fileEncSha256,
+     *         fileLength: media.fileLength,
+     *         mediaKeyTimestamp: media.mediaKeyTimestamp,
+     *         mimetype: media.mimetype
+     *     }
+     * })
+     * ```
+     */
+    upload(source: WaUploadMediaSource, options: WaUploadMediaOptions): Promise<WaMediaUploadResult>;
     /**
      * Resolves the media payload inside `source` and returns a `Readable`
      * stream of the decrypted bytes. Throws when the message has no

package/dist/client/coordinators/WaMessageCoordinator.js

@@ -5,6 +5,8 @@ const node_fs_1 = require("node:fs");
 const promises_1 = require("node:stream/promises");
 const receipt_1 = require("../events/receipt");
 const media_1 = require("../media");
+const messages_1 = require("../messaging/messages");
+const constants_1 = require("../../media/constants");
 const addon_crypto_1 = require("../../message/crypto/addon-crypto");
 const content_1 = require("../../message/encode/content");
 const _proto_1 = require("../../proto");
@@ -34,15 +36,36 @@ function parseMessageCappingMexResponse(data) {
         cappingStatus: (0, coercion_1.tryAsString)(root?.capping_status)
     };
 }
+const SIDECAR_UPLOAD_TYPES = new Set([
+    'video',
+    'ptv',
+    'audio',
+    'gif',
+    'ptt'
+]);
+async function normalizeUploadSource(source) {
+    if (source instanceof Uint8Array) {
+        return source;
+    }
+    if (typeof source === 'string') {
+        await (0, media_1.assertReadableFile)(source);
+        return (0, node_fs_1.createReadStream)(source);
+    }
+    if ((0, media_1.isReadableStream)(source)) {
+        return source;
+    }
+    throw new Error('media upload received unsupported source type');
+}
 /**
  * Coordinates outbound message sending, receipts, addon decryption, media
- * download, and the related MEX account queries. Accessed via
+ * upload/download, and the related MEX account queries. Accessed via
  * {@link WaClient.message}.
  */
 class WaMessageCoordinator {
     constructor(deps) {
         this.messageDispatch = deps.messageDispatch;
         this.mediaTransfer = deps.mediaTransfer;
+        this.mediaUploadOptions = deps.mediaUploadOptions;
         this.logger = deps.logger;
         this.messageStore = deps.messageStore;
         this.messageSecretStore = deps.messageSecretStore;
@@ -222,6 +245,58 @@ class WaMessageCoordinator {
             });
         }
     }
+    /**
+     * Encrypts and uploads standalone media to the WhatsApp CDN and returns the
+     * reusable descriptor, without sending a message - pre-upload once and
+     * reference it across sends, or build custom protos. Needs a connected
+     * session (the host token comes from a `media_conn` IQ). `source` is bytes,
+     * a file path, or a `Readable`. To send the result, spread its fields onto
+     * the matching proto message and pass that to {@link send}.
+     *
+     * @throws when `source` is unsupported, the file is unreadable, or the upload fails.
+     * @example
+     * ```ts
+     * const media = await client.message.upload(await readFile('photo.jpg'), {
+     *     type: 'image',
+     *     mimetype: 'image/jpeg'
+     * })
+     * await client.message.send(jid, {
+     *     imageMessage: {
+     *         url: media.url,
+     *         directPath: media.directPath,
+     *         mediaKey: media.mediaKey,
+     *         fileSha256: media.fileSha256,
+     *         fileEncSha256: media.fileEncSha256,
+     *         fileLength: media.fileLength,
+     *         mediaKeyTimestamp: media.mediaKeyTimestamp,
+     *         mimetype: media.mimetype
+     *     }
+     * })
+     * ```
+     */
+    async upload(source, options) {
+        const uploadPath = constants_1.MEDIA_UPLOAD_PATHS[options.type];
+        if (!uploadPath) {
+            throw new Error(`unknown media upload type: ${String(options.type)}`);
+        }
+        const result = await (0, messages_1.uploadMedia)(this.mediaUploadOptions, {
+            source: await normalizeUploadSource(source),
+            cryptoType: options.type,
+            uploadPath,
+            contentType: options.mimetype,
+            mediaKey: options.mediaKey,
+            sidecar: options.sidecar ?? SIDECAR_UPLOAD_TYPES.has(options.type),
+            firstFrameLength: options.firstFrameLength,
+            timeoutMs: options.timeoutMs,
+            signal: options.signal,
+            logLabel: 'user media upload'
+        });
+        return {
+            ...result,
+            mediaKeyTimestamp: this.mediaUploadOptions.serverClock.nowSeconds(),
+            mimetype: options.mimetype
+        };
+    }
     /**
      * Resolves the media payload inside `source` and returns a `Readable`
      * stream of the decrypted bytes. Throws when the message has no

package/dist/client/coordinators/WaMessageDispatchCoordinator.d.ts

@@ -80,8 +80,8 @@ export declare class WaMessageDispatchCoordinator {
     sendMessage(to: string, content: WaSendMessageContent, options?: WaSendMessageOptions): Promise<WaMessagePublishResult>;
     /**
      * For a 1:1 recipient passed in PN form, returns the LID-addressed user JID
-     * (cache-first; falls back to a one-shot `queryLidsByPhoneJids`). Switching
-     * to LID before fanout ensures the envelope, eligible-requester list, and
+     * (via {@link SignalDeviceSyncApi.resolveUserJidPair}). Switching to LID
+     * before fanout ensures the envelope, eligible-requester list, and
      * retry-receipt addressing all agree, which keeps the retry tracker from
      * rejecting receipts that arrive in LID form. Returns the original PN if
      * no LID is known/resolvable. Inputs already in LID form pass through.

package/dist/client/coordinators/WaMessageDispatchCoordinator.js

@@ -300,8 +300,8 @@ class WaMessageDispatchCoordinator {
     }
     /**
      * For a 1:1 recipient passed in PN form, returns the LID-addressed user JID
-     * (cache-first; falls back to a one-shot `queryLidsByPhoneJids`). Switching
-     * to LID before fanout ensures the envelope, eligible-requester list, and
+     * (via {@link SignalDeviceSyncApi.resolveUserJidPair}). Switching to LID
+     * before fanout ensures the envelope, eligible-requester list, and
      * retry-receipt addressing all agree, which keeps the retry tracker from
      * rejecting receipts that arrive in LID form. Returns the original PN if
      * no LID is known/resolvable. Inputs already in LID form pass through.
@@ -309,26 +309,8 @@ class WaMessageDispatchCoordinator {
     async resolveDirectRecipientLid(pnUserJid) {
         if ((0, jid_1.isLidJid)(pnUserJid))
             return pnUserJid;
-        const cached = await this.deps.deviceListStore.findByAnyUserJid(pnUserJid);
-        if (cached) {
-            if ((0, jid_1.isLidJid)(cached.userJid))
-                return cached.userJid;
-            if (cached.altUserJid && (0, jid_1.isLidJid)(cached.altUserJid))
-                return cached.altUserJid;
-        }
-        try {
-            const results = await this.deps.signalDeviceSync.queryLidsByPhoneJids([pnUserJid]);
-            const match = results.find((entry) => entry.queriedJid === pnUserJid);
-            if (match?.lidJid)
-                return match.lidJid;
-        }
-        catch (error) {
-            this.deps.logger.debug('lid resolution failed for direct recipient', {
-                pnUserJid,
-                message: (0, primitives_2.toError)(error).message
-            });
-        }
-        return pnUserJid;
+        const pair = await this.deps.signalDeviceSync.resolveUserJidPair(pnUserJid);
+        return pair.lidJid ?? pnUserJid;
     }
     /**
      * Resolves the `peer_recipient_pn` cross-reference for a 1:1 send, or
@@ -344,20 +326,8 @@ class WaMessageDispatchCoordinator {
             return undefined;
         if ((0, jid_1.isUserJid)(recipientUserJid))
             return recipientUserJid;
-        try {
-            const snapshot = await this.deps.deviceListStore.findByAnyUserJid(directRecipientJid);
-            if (snapshot?.userJid && (0, jid_1.isUserJid)(snapshot.userJid))
-                return snapshot.userJid;
-            if (snapshot?.altUserJid && (0, jid_1.isUserJid)(snapshot.altUserJid))
-                return snapshot.altUserJid;
-        }
-        catch (error) {
-            this.deps.logger.trace('peer_recipient_pn store lookup failed', {
-                lid: directRecipientJid,
-                message: (0, primitives_2.toError)(error).message
-            });
-        }
-        return undefined;
+        const pair = await this.deps.signalDeviceSync.resolveUserJidPair(directRecipientJid);
+        return pair.pnJid ?? undefined;
     }
     async syncSignalSession(jid, reasonIdentity = false) {
         const address = (0, jid_1.parseSignalAddressFromJid)(jid);

package/dist/client/coordinators/WaPrivacyCoordinator.d.ts

@@ -1,4 +1,5 @@
 import { type WaPrivacyDisallowedListSettingName, type WaPrivacySettingName, type WaPrivacySettingValueMap } from '../../protocol/privacy';
+import type { SignalUserJidPair } from '../../signal/api/SignalDeviceSyncApi';
 import type { BinaryNode } from '../../transport/types';
 export type WaPrivacySettings = {
     readonly [K in WaPrivacySettingName]?: WaPrivacySettingValueMap[K];
@@ -36,17 +37,29 @@ export interface WaPrivacyCoordinator {
     /** Returns the current account-wide blocklist. */
     readonly getBlocklist: () => Promise<WaBlocklistResult>;
     /**
-     * Blocks `jid` (account-wide blocklist). After this, the peer can no
-     * longer message/call you and cannot see your last seen/online/photo/
-     * status. The block is symmetric only from the peer's read perspective -
-     * they don't get an explicit "you were blocked" notification.
+     * Blocks a user (account-wide blocklist). Accepts a phone-number jid, a
+     * LID jid, or a bare phone number (digits only). After this, the peer can
+     * no longer
+     * message/call you and cannot see your last seen/online/photo/status. The
+     * block is symmetric only from the peer's read perspective - they don't
+     * get an explicit "you were blocked" notification.
+     *
+     * The server keys blocklist entries by LID for migrated accounts, so a
+     * phone-number input is resolved to its LID first (device-list cache,
+     * then a usync query). Non-migrated accounts fall back to the plain
+     * phone-jid form.
      */
     readonly blockUser: (jid: string) => Promise<void>;
-    /** Removes `jid` from the blocklist. */
+    /**
+     * Removes a user from the blocklist. Accepts the same inputs as
+     * {@link blockUser} and performs the same LID resolution - unblocking a
+     * migrated entry by phone jid is rejected by the server.
+     */
     readonly unblockUser: (jid: string) => Promise<void>;
 }
 interface WaPrivacyCoordinatorOptions {
     readonly queryWithContext: (context: string, node: BinaryNode, timeoutMs?: number, contextData?: Readonly<Record<string, unknown>>) => Promise<BinaryNode>;
+    readonly resolveUserJidPair: (userJid: string) => Promise<SignalUserJidPair>;
 }
 /** Builds a {@link WaPrivacyCoordinator} backed by the given IQ query function. */
 export declare function createPrivacyCoordinator(options: WaPrivacyCoordinatorOptions): WaPrivacyCoordinator;

package/dist/client/coordinators/WaPrivacyCoordinator.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createPrivacyCoordinator = createPrivacyCoordinator;
+const jid_1 = require("../../protocol/jid");
 const nodes_1 = require("../../protocol/nodes");
 const privacy_1 = require("../../protocol/privacy");
 const privacy_2 = require("../../transport/node/builders/privacy");
@@ -88,6 +89,23 @@ function parseBlocklist(result) {
     jids.length = jidsCount;
     return { jids, dhash };
 }
+/**
+ * Resolves a blocklist input into both addressing forms via
+ * `resolveUserJidPair` (device-list cache first, usync fallback for phone
+ * jids). Resolution failures degrade to the single known form instead of
+ * throwing - the server then decides whether that form is acceptable.
+ */
+async function resolveBlocklistTarget(options, jid) {
+    const normalized = (0, jid_1.normalizeRecipientJid)(jid);
+    if (!(0, jid_1.isLidJid)(normalized) && !(0, jid_1.isUserJid)(normalized)) {
+        throw new Error(`blocklist target must be a user jid: ${jid}`);
+    }
+    const pair = await options.resolveUserJidPair(normalized);
+    if (pair.lidJid !== null) {
+        return { lidJid: pair.lidJid, pnJid: pair.pnJid };
+    }
+    return { lidJid: null, pnJid: pair.pnJid ?? normalized };
+}
 /** Builds a {@link WaPrivacyCoordinator} backed by the given IQ query function. */
 function createPrivacyCoordinator(options) {
     const { queryWithContext } = options;
@@ -123,13 +141,20 @@ function createPrivacyCoordinator(options) {
             return parseBlocklist(result);
         },
         blockUser: async (jid) => {
-            const node = (0, privacy_2.buildBlocklistChangeIq)(jid, 'block');
-            const result = await queryWithContext('privacy.blockUser', node, undefined, { jid });
+            const target = await resolveBlocklistTarget(options, jid);
+            const node = (0, privacy_2.buildBlocklistBlockIq)(target);
+            const result = await queryWithContext('privacy.blockUser', node, undefined, {
+                jid: target.lidJid ?? target.pnJid
+            });
             (0, query_1.assertIqResult)(result, 'privacy.blockUser');
         },
         unblockUser: async (jid) => {
-            const node = (0, privacy_2.buildBlocklistChangeIq)(jid, 'unblock');
-            const result = await queryWithContext('privacy.unblockUser', node, undefined, { jid });
+            const target = await resolveBlocklistTarget(options, jid);
+            const unblockJid = target.lidJid ?? target.pnJid;
+            const node = (0, privacy_2.buildBlocklistUnblockIq)(unblockJid);
+            const result = await queryWithContext('privacy.unblockUser', node, undefined, {
+                jid: unblockJid
+            });
             (0, query_1.assertIqResult)(result, 'privacy.unblockUser');
         }
     };

package/dist/client/media.d.ts

@@ -57,6 +57,7 @@ export interface ResolvedMediaInputs {
     readonly uploadMedia: Uint8Array | Readable;
     readonly tempFilePath?: string;
 }
+export declare function assertReadableFile(filePath: string): Promise<void>;
 export declare function resolveMediaInputs(shouldProcess: boolean, raw: Uint8Array | ArrayBuffer | Readable | string): Promise<ResolvedMediaInputs>;
 export declare function shouldNormalizeVoiceNote(media: WaMediaOptions | undefined, content: WaSendMediaMessage): content is WaSendMediaMessage & {
     type: 'audio';

package/dist/client/media.js

@@ -9,6 +9,7 @@ exports.buildMediaUploadUrl = buildMediaUploadUrl;
 exports.assertMediaUploadStatus = assertMediaUploadStatus;
 exports.parseMediaUploadJsonBody = parseMediaUploadJsonBody;
 exports.performPlaintextMediaUpload = performPlaintextMediaUpload;
+exports.assertReadableFile = assertReadableFile;
 exports.resolveMediaInputs = resolveMediaInputs;
 exports.shouldNormalizeVoiceNote = shouldNormalizeVoiceNote;
 exports.hasMediaProcessingTasks = hasMediaProcessingTasks;

package/dist/client/messaging/messages.d.ts

@@ -1,8 +1,9 @@
+import { Readable } from 'node:stream';
 import type { ResolvedLinkPreviewResult } from '../messaging/link-preview';
 import type { WaMediaOptions } from '../types';
 import type { Logger } from '../../infra/log/types';
 import type { WaMediaTransferClient } from '../../media/transfer/WaMediaTransferClient';
-import type { WaMediaConn } from '../../media/types';
+import type { MediaCryptoType, WaMediaConn } from '../../media/types';
 import type { WaMessageBuildResult, WaSendMessageContent, WaSendTextMessage } from '../../message/types';
 import type { BinaryNode } from '../../transport/types';
 import type { ServerClock } from '../../util/clock';
@@ -26,3 +27,46 @@ export interface WaBuildMessageContext {
 }
 export declare function buildMediaMessageContent(options: WaMediaMessageOptions, content: WaSendMessageContent, ctx?: WaBuildMessageContext): Promise<WaMessageBuildResult>;
 export declare function getMediaConn(options: WaMediaMessageOptions, forceRefresh?: boolean): Promise<WaMediaConn>;
+/** Descriptor produced by {@link uploadMedia}: CDN location, media key, hashes, and optional sidecars. */
+export interface UploadResult {
+    /** Absolute CDN URL of the uploaded ciphertext. */
+    readonly url: string;
+    /** Host-relative path; pairs with a media host or feeds `downloadMediaMessage`. */
+    readonly directPath: string;
+    /** 32-byte media key used to encrypt (and later decrypt) the payload. */
+    readonly mediaKey: Uint8Array;
+    /** SHA-256 of the plaintext. */
+    readonly fileSha256: Uint8Array;
+    /** SHA-256 of the encrypted `ciphertext||mac`. */
+    readonly fileEncSha256: Uint8Array;
+    /** Plaintext byte length. */
+    readonly fileLength: number;
+    /** Server metadata URL, when the CDN returns one (video). */
+    readonly metadataUrl?: string;
+    /** Streaming sidecar for seekable playback, when computed. */
+    readonly streamingSidecar?: Uint8Array;
+    /** First-frame sidecar for animated stickers, when computed. */
+    readonly firstFrameSidecar?: Uint8Array;
+    /** First-frame length echoed back for animated stickers. */
+    readonly firstFrameLength?: number;
+}
+/** Fully-resolved input for {@link uploadMedia} (crypto type, path, sidecar already decided). */
+export interface WaMediaUploadInput {
+    readonly source: Uint8Array | Readable;
+    readonly cryptoType: MediaCryptoType;
+    readonly uploadPath: string;
+    readonly contentType?: string;
+    readonly mediaKey?: Uint8Array;
+    readonly sidecar: boolean;
+    readonly firstFrameLength?: number;
+    readonly logLabel?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Shared media upload primitive: derives (or reuses) a media key, encrypts,
+ * fetches a media connection, and POSTs the ciphertext. Bytes take a
+ * zero-temp-file fast path; streams stage to a temp file first. Backs both the
+ * send path and `WaMessageCoordinator.upload`.
+ */
+export declare function uploadMedia(options: WaMediaMessageOptions, input: WaMediaUploadInput): Promise<UploadResult>;