# Changelog of Universal Downloader (`dz_omar/universal-downloader`) Actor

- **URL**: https://apify.com/dz\_omar/universal-downloader/changelog.md
- **Full Actor documentation**: https://apify.com/dz\_omar/universal-downloader.md

## Changelog

All notable changes to the Universal File Downloader Actor will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

### \[0.2] - 2025-01-20

#### 🎉 Major Release - Unique Filename Generation

This release introduces a game-changing feature that prevents file overwrites when downloading multiple files with identical names.

#### Added

- **Unique Filename Generation** - Smart hash-based naming system to prevent file conflicts
  - Adds 6-character MD5 hash derived from the full URL to each filename
  - Format: `originalName-hash.extension` (e.g., `hqdefault-a3f5c2.jpg`)
  - Deterministic: Same URL always produces the same hash
  - Enabled by default with `uniqueFileNames: true`
  - Can be disabled by setting `uniqueFileNames: false`
- New input parameter `uniqueFileNames` in input schema (default: `true`)
- `addUniqueHash()` function in `fileUtils.js` for hash generation
- Support for unique naming in HLS conversion (Zoom clips)
- Unique filename support in standby mode API endpoint
- Detailed logging when unique filenames are enabled/disabled

#### Changed

- `generateSafeFileName()` now accepts `makeUnique` parameter
- `DownloadEngine.download()` now accepts `uniqueFileNames` parameter
- `DownloadProcessor.processUrls()` now accepts `uniqueFileNames` parameter
- `HLSConverter.convert()` now accepts `uniqueFileNames` parameter
- `InputProcessor.process()` now extracts and returns `uniqueFileNames` setting
- `AppController.runNormalMode()` passes `uniqueFileNames` through the chain
- API endpoint `/api/download` now supports `uniqueFileNames` parameter
- Updated API status endpoint to include `unique_filenames: true` feature flag
- Enhanced example payloads in comments to show `uniqueFileNames` option

#### Fixed

- Files with identical names no longer overwrite each other
- Multiple YouTube thumbnails (`hqdefault.jpg`) now save as unique files
- Zoom HLS converted videos now support unique naming
- API download requests preserve filename uniqueness settings

#### Documentation

- Updated README.md with comprehensive unique filename documentation
- Added "Unique Filename Feature" section explaining how it works
- Added example showing YouTube thumbnail downloads without overwrites
- Updated all input examples to include `uniqueFileNames` parameter
- Added "When to Disable" guidance for the feature
- Updated "Common Issues and Solutions" section
- Enhanced "Best Practices" with unique filename recommendations

#### Breaking Changes

⚠️ **Default Behavior Changed**: Files now get unique names by default (`uniqueFileNames: true`)

- **Impact**: Existing workflows will now produce files with hashes appended
- **Migration**: Set `uniqueFileNames: false` to restore old behavior (overwrites allowed)
- **Recommendation**: Keep the new default for better reliability

***

### \[0.1.2] - 2025-01-10

#### Added

- Automatic `Content-Type: application/json` header injection when payload is provided
- Standby mode improvements for n8n/webhook integrations
- Better error handling for missing request fields

#### Fixed

- Proxy test endpoint now handles missing fields more gracefully
- Improved error logging for failed downloads
- Better handling of malformed API requests

#### Changed

- Enhanced request validation in WebServer endpoints
- Improved debug logging for proxy configuration

***

### \[0.1.1] - 2025-01-01

#### Initial Release

#### Security

- Input validation for URLs and parameters
- Filename sanitization to prevent injection attacks
- Secure file storage with signed URLs
- Error isolation between downloads

#### Documentation

- Comprehensive README with examples
- API endpoint documentation
- Standby mode setup guide
- Input/output schema documentation
- Troubleshooting guide

***

### Version History Summary

- **0.1.1** (2025-01-20): Major release with unique filename generation
- **0.1.2** (2025-01-10): Improvements and fixes
- **0.2** (2025-01-01): Initial release

***