fix MessageMedia creator with remote file url

[keelvin]

PR Details

Description

This PR enhances the MessageMedia.fromUrl() method by adding comprehensive file size validation to prevent failures when attempting to send media files that exceed WhatsApp's size limits. The enhancement includes pre-download validation, specific limits per media type, and detailed error reporting.

Key Changes:

• Pre-download validation: Uses HEAD request to check file size before downloading
• Type-specific limits: Implements WhatsApp's actual size limits per media type
• Enhanced error handling: Provides detailed error messages with file size information
• Improved logging: Adds detailed console logs for debugging and monitoring
• Base64 validation: Ensures downloaded data integrity

Related Issue(s)

Motivation and Context

Problem Solved:

When using MessageMedia.fromUrl() with large files (>64MB), the library would:

1. Download the entire file consuming bandwidth and memory
2. Attempt to send it through WhatsApp Web
3. Fail silently or with cryptic protocol errors
4. Potentially cause session timeouts or memory issues

WhatsApp Size Limits:

• Images: 16MB
• Videos: 64MB
• Audio: 16MB
• Documents: 100MB

Why This Change is Required:

• User Experience: Provides clear, actionable error messages
• Performance: Prevents unnecessary large file downloads
• Reliability: Reduces session timeouts and memory issues
• Developer Experience: Better debugging with detailed logs

How Has This Been Tested

Test Scenarios:

1. Valid files within limits:

   • ✅ Small video (5MB) - Success
   • ✅ Medium video (40MB) - Success
   • ✅ Large image (10MB) - Success

2. Files exceeding limits:

   • ❌ Large video (210MB) - Proper error with detailed message
   • ❌ Large image (20MB) - Proper error for image limit
   • ❌ Large audio (25MB) - Proper error for audio limit

3. Edge cases:

   • ✅ Files without Content-Length header - Falls back to download with validation
   • ✅ Network errors during HEAD request - Graceful fallback
   • ✅ Invalid URLs - Proper error handling

Error Message Example:

Error: File size (210.50MB) exceeds WhatsApp limit for video/mp4 (64MB). Maximum allowed: 64MB, Got: 210.50MB

Environment

• Machine OS: macOS / Linux / Windows
• Phone OS: Android / iOS
• Library Version: whatsapp-web.js@latest
• WhatsApp Web Version: (run await client.getWWebVersion())
• Puppeteer Version: ^21.0.0
• Browser Type and Version: Chromium (latest)
• Node Version: v18.x / v20.x

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Dependency change

Checklist

• My code follows the code style of this project.
• I have updated the documentation accordingly (index.d.ts).
• I have updated the usage example accordingly (example.js)

Additional Notes

Backward Compatibility:

• ✅ Fully backward compatible - existing code continues to work
• ✅ Non-breaking - only adds validation, doesn't change API
• ✅ Opt-in warnings - provides helpful information without disrupting flow

Performance Impact:

• ✅ Positive impact - prevents large unnecessary downloads
• ✅ Minimal overhead - HEAD request is lightweight
• ✅ Graceful fallback - if HEAD fails, continues with normal flow

Error Handling:

• ✅ Structured errors - includes error codes and metadata
• ✅ Actionable messages - tells users exactly what limits were exceeded
• ✅ Developer-friendly - includes all relevant debugging information

Future Enhancements:

This change provides a foundation for potential future features like:

• Automatic file compression for oversized media
• Intelligent media type conversion (e.g., large video → document)
• Progress callbacks for large file downloads

[lindionez]

In my application, I download audios larger than 16MB, and send them in document format. Audio smaller than 16MB? send as audio. Is it bigger? as file.

[purpshell]

good validation

[BenyFilho]

@keelvin will you update it to comply with the latest changes? Do you know if this fix is still necessary?