zapo-js 1.5.0 → 1.6.0

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

@@ -504,6 +504,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/WaAppStateMutationCoordinator.js

@@ -761,8 +761,8 @@ class WaAppStateMutationCoordinator {
             statusPrivacy: {
                 mode: modeValue,
                 userJid,
-                ...(input.shareToFB === undefined ? {} : { shareToFB: input.shareToFB }),
-                ...(input.shareToIG === undefined ? {} : { shareToIG: input.shareToIG })
+                ...(input.shareToFB === undefined ? {} : { shareToFb: input.shareToFB }),
+                ...(input.shareToIG === undefined ? {} : { shareToIg: input.shareToIG })
             }
         };
         const timestamp = this.serverClock.nowMs();

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.js

@@ -318,7 +318,7 @@ class WaMessageDispatchCoordinator {
         }
         try {
             const results = await this.deps.signalDeviceSync.queryLidsByPhoneJids([pnUserJid]);
-            const match = results.find((entry) => entry.phoneJid === pnUserJid);
+            const match = results.find((entry) => entry.queriedJid === pnUserJid);
             if (match?.lidJid)
                 return match.lidJid;
         }

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>;

package/dist/client/messaging/messages.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildMediaMessageContent = buildMediaMessageContent;
 exports.getMediaConn = getMediaConn;
+exports.uploadMedia = uploadMedia;
 const node_fs_1 = require("node:fs");
 const node_stream_1 = require("node:stream");
 const media_1 = require("../media");
@@ -345,9 +346,15 @@ async function buildMediaMessage(options, content) {
         const firstFrameLength = content.type === 'sticker'
             ? (content.firstFrameLength ?? detectedFirstFrameLength)
             : undefined;
-        const uploadPromise = (0, media_1.isReadableStream)(resolved.uploadMedia)
-            ? uploadMediaStream(options, content, resolved.uploadMedia, firstFrameLength, mimetype)
-            : uploadMediaBytes(options, content, resolved.uploadMedia, firstFrameLength, mimetype);
+        const uploadType = resolveUploadType(content);
+        const uploadPromise = uploadMedia(options, {
+            source: resolved.uploadMedia,
+            cryptoType: uploadType,
+            uploadPath: resolveUploadPath(uploadType),
+            contentType: mimetype,
+            sidecar: needsSidecar(content),
+            firstFrameLength
+        });
         const processPromise = (0, media_1.runMediaProcessor)(options.media, resolved.processorInput, content, options.logger);
         const [uploadResult, processResult] = await Promise.allSettled([
             uploadPromise,
@@ -508,29 +515,42 @@ function parseUploadResponse(body, status) {
         ...(parsed.metadata_url ? { metadataUrl: parsed.metadata_url } : {})
     };
 }
-async function uploadMediaBytes(options, content, mediaBytes, firstFrameLength, mimetype) {
-    const uploadType = resolveUploadType(content);
-    const mediaKey = await WaMediaCrypto_1.WaMediaCrypto.generateMediaKey();
+/**
+ * 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`.
+ */
+async function uploadMedia(options, input) {
+    const mediaKey = input.mediaKey ?? (await WaMediaCrypto_1.WaMediaCrypto.generateMediaKey());
+    if (input.source instanceof Uint8Array) {
+        return uploadMediaBytes(options, input, mediaKey, input.source);
+    }
+    return uploadMediaStream(options, input, mediaKey, input.source);
+}
+async function uploadMediaBytes(options, input, mediaKey, mediaBytes) {
     const [encrypted, mediaConn] = await Promise.all([
-        WaMediaCrypto_1.WaMediaCrypto.encryptBytes(uploadType, mediaKey, mediaBytes, {
-            sidecar: needsSidecar(content),
-            firstFrameLength
+        WaMediaCrypto_1.WaMediaCrypto.encryptBytes(input.cryptoType, mediaKey, mediaBytes, {
+            sidecar: input.sidecar,
+            firstFrameLength: input.firstFrameLength
         }),
         getMediaConn(options)
     ]);
     const selectedHost = (0, media_1.selectMediaUploadHost)(mediaConn);
-    const uploadUrl = (0, media_1.buildMediaUploadUrl)(selectedHost, resolveUploadPath(uploadType), mediaConn.auth, encrypted.fileEncSha256);
-    options.logger.debug('sending media upload request', {
-        mediaType: content.type,
-        uploadType,
-        host: selectedHost
+    const uploadUrl = (0, media_1.buildMediaUploadUrl)(selectedHost, input.uploadPath, mediaConn.auth, encrypted.fileEncSha256);
+    options.logger.debug(input.logLabel ?? 'sending media upload request', {
+        cryptoType: input.cryptoType,
+        host: selectedHost,
+        size: mediaBytes.byteLength
     });
     const uploadResponse = await options.mediaTransfer.uploadStream({
         url: uploadUrl,
         method: 'POST',
         body: encrypted.ciphertextHmac,
         contentLength: encrypted.ciphertextHmac.byteLength,
-        contentType: mimetype
+        contentType: input.contentType,
+        timeoutMs: input.timeoutMs,
+        signal: input.signal
     });
     const responseBody = await options.mediaTransfer.readResponseBytes(uploadResponse);
     const parsed = parseUploadResponse(responseBody, uploadResponse.status);
@@ -542,19 +562,22 @@ async function uploadMediaBytes(options, content, mediaBytes, firstFrameLength,
         fileLength: mediaBytes.byteLength,
         streamingSidecar: encrypted.streamingSidecar,
         firstFrameSidecar: encrypted.firstFrameSidecar,
-        firstFrameLength
+        firstFrameLength: input.firstFrameLength
     };
 }
-async function uploadEncryptedStream(options, input) {
-    const encResult = await WaMediaCrypto_1.WaMediaCrypto.encryptToFile(input.cryptoType, input.mediaKey, input.plaintext, { sidecar: input.sidecar, firstFrameLength: input.firstFrameLength });
+async function uploadMediaStream(options, input, mediaKey, plaintext) {
+    const encResult = await WaMediaCrypto_1.WaMediaCrypto.encryptToFile(input.cryptoType, mediaKey, plaintext, {
+        sidecar: input.sidecar,
+        firstFrameLength: input.firstFrameLength
+    });
     let readStream;
     try {
         const mediaConn = await getMediaConn(options);
         const selectedHost = (0, media_1.selectMediaUploadHost)(mediaConn);
         const uploadUrl = (0, media_1.buildMediaUploadUrl)(selectedHost, input.uploadPath, mediaConn.auth, encResult.fileEncSha256);
-        options.logger.debug(input.logLabel, {
+        options.logger.debug(input.logLabel ?? 'sending media stream upload request', {
+            cryptoType: input.cryptoType,
             host: selectedHost,
-            uploadPath: input.uploadPath,
             plaintextLength: encResult.plaintextLength,
             encryptedSize: encResult.fileSize
         });
@@ -564,13 +587,15 @@ async function uploadEncryptedStream(options, input) {
             method: 'POST',
             body: readStream,
             contentLength: encResult.fileSize,
-            contentType: input.contentType
+            contentType: input.contentType,
+            timeoutMs: input.timeoutMs,
+            signal: input.signal
         });
         const responseBody = await options.mediaTransfer.readResponseBytes(uploadResponse);
         const parsed = parseUploadResponse(responseBody, uploadResponse.status);
         return {
             ...parsed,
-            mediaKey: input.mediaKey,
+            mediaKey,
             fileSha256: encResult.fileSha256,
             fileEncSha256: encResult.fileEncSha256,
             fileLength: encResult.plaintextLength,
@@ -589,19 +614,6 @@ async function uploadEncryptedStream(options, input) {
         await WaMediaCrypto_1.WaMediaCrypto.cleanupEncryptedFile(encResult.filePath);
     }
 }
-async function uploadMediaStream(options, content, stream, firstFrameLength, mimetype) {
-    const cryptoType = resolveUploadType(content);
-    return uploadEncryptedStream(options, {
-        plaintext: stream,
-        mediaKey: await WaMediaCrypto_1.WaMediaCrypto.generateMediaKey(),
-        cryptoType,
-        uploadPath: resolveUploadPath(cryptoType),
-        contentType: mimetype,
-        logLabel: 'sending media stream upload request',
-        sidecar: needsSidecar(content),
-        firstFrameLength
-    });
-}
 function openStickerPackInputStream(media) {
     return typeof media === 'string' ? (0, node_fs_1.createReadStream)(media) : node_stream_1.Readable.from([media]);
 }
@@ -613,23 +625,23 @@ async function buildStickerPackMediaMessage(options, content) {
     const coverThumbnail = content.coverThumbnail;
     const mediaKey = await WaMediaCrypto_1.WaMediaCrypto.generateMediaKey();
     const [bundle, cover] = await Promise.all([
-        uploadEncryptedStream(options, {
-            plaintext: (0, sticker_pack_1.createStickerPackZipStream)((0, sticker_pack_2.toStickerPackZipEntries)(content)),
-            mediaKey,
+        uploadMedia(options, {
+            source: (0, sticker_pack_1.createStickerPackZipStream)((0, sticker_pack_2.toStickerPackZipEntries)(content)),
             cryptoType: 'sticker-pack',
             uploadPath: constants_1.MEDIA_UPLOAD_PATHS['sticker-pack'],
             contentType: 'application/zip',
-            logLabel: 'sending sticker pack bundle upload',
-            sidecar: false
-        }),
-        uploadEncryptedStream(options, {
-            plaintext: openStickerPackInputStream(coverThumbnail),
             mediaKey,
+            sidecar: false,
+            logLabel: 'sending sticker pack bundle upload'
+        }),
+        uploadMedia(options, {
+            source: openStickerPackInputStream(coverThumbnail),
             cryptoType: 'thumbnail-sticker-pack',
             uploadPath: constants_1.MEDIA_UPLOAD_PATHS['thumbnail-sticker-pack'],
             contentType: 'image/jpeg',
-            logLabel: 'sending sticker pack thumbnail upload',
-            sidecar: false
+            mediaKey,
+            sidecar: false,
+            logLabel: 'sending sticker pack thumbnail upload'
         })
     ]);
     if (cover.fileLength === 0) {

package/dist/esm/client/WaClient.js

@@ -411,7 +411,7 @@ class WaClientImpl extends 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/esm/client/WaClientFactory.js

@@ -500,6 +500,7 @@ export function buildWaClientDependencies(input) {
     const messageCoordinator = new WaMessageCoordinator({
         messageDispatch,
         mediaTransfer,
+        mediaUploadOptions: mediaMessageBuildOptions,
         logger,
         messageStore: sessionStore.messages,
         messageSecretStore: sessionStore.messageSecret,

package/dist/esm/client/coordinators/WaAppStateMutationCoordinator.js

@@ -758,8 +758,8 @@ export class WaAppStateMutationCoordinator {
             statusPrivacy: {
                 mode: modeValue,
                 userJid,
-                ...(input.shareToFB === undefined ? {} : { shareToFB: input.shareToFB }),
-                ...(input.shareToIG === undefined ? {} : { shareToIG: input.shareToIG })
+                ...(input.shareToFB === undefined ? {} : { shareToFb: input.shareToFB }),
+                ...(input.shareToIG === undefined ? {} : { shareToIg: input.shareToIG })
             }
         };
         const timestamp = this.serverClock.nowMs();

package/dist/esm/client/coordinators/WaMessageCoordinator.js

@@ -1,7 +1,9 @@
-import { createWriteStream } from 'node:fs';
+import { createReadStream, createWriteStream } from 'node:fs';
 import { pipeline } from 'node:stream/promises';
 import { aggregateReceiptTargets } from '../events/receipt.js';
-import { downloadMediaMessage } from '../media.js';
+import { assertReadableFile, downloadMediaMessage, isReadableStream } from '../media.js';
+import { uploadMedia } from '../messaging/messages.js';
+import { MEDIA_UPLOAD_PATHS } from '../../media/constants.js';
 import { buildAddonAdditionalData, decodeAddonPlaintext, decryptAddonPayload, identifyEncryptedAddon, resolveParentMessageSecret, resolvePollOptionNames, shouldUseAddonAdditionalData } from '../../message/crypto/addon-crypto.js';
 import { unwrapMessage } from '../../message/encode/content.js';
 import { proto } from '../../proto.js';
@@ -31,15 +33,36 @@ function parseMessageCappingMexResponse(data) {
         cappingStatus: 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 assertReadableFile(source);
+        return createReadStream(source);
+    }
+    if (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}.
  */
 export 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;
@@ -219,6 +242,58 @@ export 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 = MEDIA_UPLOAD_PATHS[options.type];
+        if (!uploadPath) {
+            throw new Error(`unknown media upload type: ${String(options.type)}`);
+        }
+        const result = await 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