feat: support big file downloads (read from WA cache + streaming) (#201697)

* feat: support big file downloads (read from WA cache + streaming)

* fix: simplify downloadMediaStream to use a single handle

instead of two handles (resultHandle + blobHandle) with disposal gaps,
get the blob handle directly from evaluateHandle and read metadata
via blobHandle.evaluate. This eliminates the intermediate resultHandle
entirely.

blobhandle is disposed in all exit paths: null metadata, evaluate
error, and generator finally.

index.d.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from 'events';
+import { Readable } from 'stream';
 import { RequestInit } from 'node-fetch';
 import * as puppeteer from 'puppeteer';
 import InterfaceController from './src/util/InterfaceController';
@@ -198,7 +199,7 @@ declare namespace WAWebJS {
         ): Promise<string>;
 
         /** Cancels an active pairing code session and returns to QR code mode */
-        cancelPairingCode(): Promise<void>
+        cancelPairingCode(): Promise<void>;
 
         /** Force reset of connection state for the client */
         resetState(): Promise<void>;
@@ -1308,7 +1309,11 @@ declare namespace WAWebJS {
         /** Deletes the message from the chat */
         delete: (everyone?: boolean, clearMedia?: boolean) => Promise<void>;
         /** Downloads and returns the attached message media */
-        downloadMedia: () => Promise<MessageMedia>;
+        downloadMedia: () => Promise<MessageMedia | undefined>;
+        /** Downloads the attached message media as a Node.js Readable stream */
+        downloadMediaStream: (
+            options?: MediaStreamOptions,
+        ) => Promise<MessageMediaStream | undefined>;
         /** Returns the Chat this message was sent in */
         getChat: () => Promise<Chat>;
         /** Returns the Contact this message was sent from */
@@ -1616,8 +1621,18 @@ declare namespace WAWebJS {
         reqOptions?: RequestInit;
     }
 
+    /** Common metadata for media attached to a message */
+    export interface MessageMediaMetadata {
+        /** MIME type of the attachment */
+        mimetype: string;
+        /** Document file name. Value can be null */
+        filename?: string | null;
+        /** Document file size in bytes. Value can be null. */
+        filesize?: number | null;
+    }
+
     /** Media attached to a message */
-    export class MessageMedia {
+    export class MessageMedia implements MessageMediaMetadata {
         /** MIME type of the attachment */
         mimetype: string;
         /** Base64-encoded data of the file */
@@ -1650,6 +1665,17 @@ declare namespace WAWebJS {
         ) => Promise<MessageMedia>;
     }
 
+    /** Options for downloadMediaStream */
+    export interface MediaStreamOptions {
+        /** Size in bytes of each chunk read from the browser (default 10MB) */
+        chunkSize?: number;
+    }
+
+    /** Result of downloadMediaStream: a Readable stream with media metadata */
+    export interface MessageMediaStream extends MessageMediaMetadata {
+        stream: Readable;
+    }
+
     export type MessageContent =
         | string
         | MessageMedia