@ohos-ports/electron-dl 0.0.0-stage → 5.0.0-beta.0

package/index.d.ts

@@ -0,0 +1,255 @@
+import {
+	type BrowserWindow,
+	type DownloadItem,
+	type SaveDialogOptions,
+	type WebContentsView,
+} from 'electron';
+
+export type Progress = {
+	percent: number;
+	transferredBytes: number;
+	totalBytes: number;
+};
+
+export type File = {
+	filename: string;
+	path: string;
+	fileSize: number;
+	mimeType: string;
+	url: string;
+};
+
+export type Options = {
+	/**
+	Show a `Save As…` dialog instead of downloading immediately.
+
+	Note: Only use this option when strictly necessary. Downloading directly without a prompt is a much better user experience.
+
+	@default false
+	*/
+	readonly saveAs?: boolean;
+
+	/**
+	The directory to save the file in.
+
+	Must be an absolute path.
+
+	Default: [User's downloads directory](https://electronjs.org/docs/api/app/#appgetpathname)
+	*/
+	readonly directory?: string;
+
+	/**
+	Name of the saved file.
+
+	Must not contain a path separator, so it cannot point outside `directory`.
+
+	This option only makes sense for `electronDl.download()`.
+
+	Default: [`downloadItem.getFilename()`](https://electronjs.org/docs/api/download-item/#downloaditemgetfilename)
+	*/
+	readonly filename?: string;
+
+	/**
+	Title of the error dialog. Can be customized for localization.
+
+	Note: Error dialog will not be shown in `electronDl.download()`. Please handle error manually.
+
+	@default 'Download Error'
+	*/
+	readonly errorTitle?: string;
+
+	/**
+	Message of the error dialog. `{filename}` is replaced with the name of the actual file. Can be customized for localization.
+
+	Note: Error dialog will not be shown in `electronDl.download()`. Please handle error manually.
+
+	@default 'The download of {filename} was interrupted'
+	*/
+	readonly errorMessage?: string;
+
+	/**
+	Optional callback that receives the [download item](https://electronjs.org/docs/api/download-item).
+	You can use this for advanced handling such as canceling the item like `item.cancel()`.
+	*/
+	readonly onStarted?: (item: DownloadItem) => void;
+
+	/**
+	Optional callback that receives an object containing information about the progress of the current download item.
+	*/
+	readonly onProgress?: (progress: Progress) => void;
+
+	/**
+	Optional callback that receives an object containing information about the combined progress of all download items done within any registered window.
+
+	Each time a new download is started, the next callback will include it. The progress percentage could therefore become smaller again.
+	This callback provides the same data that is used for the progress bar on the app icon.
+	*/
+	readonly onTotalProgress?: (progress: Progress) => void;
+
+	/**
+	Optional callback that receives the [download item](https://electronjs.org/docs/api/download-item) for which the download has been cancelled.
+	*/
+	readonly onCancel?: (item: DownloadItem) => void;
+
+	/**
+	Optional callback that receives an object with information about an item that has been completed. It is called for each completed item.
+	*/
+	readonly onCompleted?: (file: File) => void;
+
+	/**
+	Optional callback that receives the `Error` for a download that was interrupted and could not be resumed.
+
+	When this is provided, the error dialog is not shown.
+
+	This option only makes sense for the default export. `electronDl.download()` rejects with the error instead.
+
+	@example
+	```
+	import electronDl from 'electron-dl';
+
+	electronDl({
+		onError(error) {
+			console.error(error.message);
+		}
+	});
+	```
+	*/
+	readonly onError?: (error: Error) => void;
+
+	/**
+	Reveal the downloaded file in the system file manager, and if possible, select the file.
+
+	@default false
+	*/
+	readonly openFolderWhenDone?: boolean;
+
+	/**
+	Show a file count badge on the macOS/Linux dock/taskbar icon when a download is in progress.
+
+	@default true
+	*/
+	readonly showBadge?: boolean;
+
+	/**
+	Show a progress bar on the dock/taskbar icon when a download is in progress.
+
+	Downloads without an associated `BrowserWindow` are saved normally, but do not show a progress bar.
+
+	@default true
+	*/
+	readonly showProgressBar?: boolean;
+
+	/**
+	Allow downloaded files to overwrite files with the same name in the directory they are saved to.
+
+	The default behavior is to append a number to the filename.
+
+	@default false
+	*/
+	readonly overwrite?: boolean;
+
+	/**
+	Customize the save dialog.
+
+	If `defaultPath` is not explicity defined, a default value is assigned based on the file path.
+
+	@default {}
+	*/
+	readonly dialogOptions?: SaveDialogOptions;
+};
+
+export type BytesOptions = {
+	/**
+	Optional callback that receives an object containing information about the progress of the download.
+
+	`percent` is `0` when the total size is not known, for example for a compressed or chunked response.
+	*/
+	readonly onProgress?: (progress: Progress) => void;
+
+	/**
+	An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) to cancel the download with. An aborted download rejects with the signal's abort reason, which defaults to an `AbortError`.
+	*/
+	readonly signal?: AbortSignal;
+};
+
+/**
+Error thrown if `item.cancel()` was called.
+*/
+export class CancelError extends Error {}
+
+/**
+Register the helper for all windows.
+
+@example
+```
+import {app, BrowserWindow} from 'electron';
+import electronDl from 'electron-dl';
+
+electronDl();
+
+let mainWindow;
+(async () => {
+	await app.whenReady();
+	mainWindow = new BrowserWindow();
+})();
+```
+*/
+export default function electronDl(options?: Options): void;
+
+/**
+This can be useful if you need download functionality in a reusable module.
+
+An interrupted download is resumed automatically when the server supports it, as long as the app is running. A download is not resumed after the app is restarted, since that would need the app to persist the download state.
+
+@param window - Window to register the behavior on.
+@param url - URL to download.
+@returns A promise for the downloaded file.
+@throws {CancelError} An error if the user calls `item.cancel()`.
+@throws {Error} An error if the download fails.
+
+@example
+```
+import {BrowserWindow, ipcMain} from 'electron';
+import {download} from 'electron-dl';
+
+ipcMain.on('download-button', async (event, {url}) => {
+	const win = BrowserWindow.getFocusedWindow();
+	console.log(await download(win, url));
+});
+```
+*/
+export function download(
+	window: BrowserWindow | WebContentsView,
+	url: string,
+	options?: Options,
+): Promise<DownloadItem>;
+
+/**
+Download a file into memory instead of saving it to disk. Use this when you want to process the file directly.
+
+The download does not appear in the Downloads directory. It is not shown in the dock/taskbar badge or progress bar, and it cannot be resumed.
+
+The promise rejects when the server responds with an error status.
+
+@param window - Window to download with.
+@param url - URL to download.
+@returns A promise for the contents of the downloaded file.
+@throws {Error} An error if the download fails.
+
+@example
+```
+import {BrowserWindow, ipcMain} from 'electron';
+import {downloadAsBytes} from 'electron-dl';
+
+ipcMain.on('download-button', async (event, {url}) => {
+	const win = BrowserWindow.getFocusedWindow();
+	const bytes = await downloadAsBytes(win, url);
+	console.log(bytes.length);
+});
+```
+*/
+export function downloadAsBytes(
+	window: BrowserWindow | WebContentsView,
+	url: string,
+	options?: BytesOptions,
+): Promise<Uint8Array>;

package/index.js

@@ -0,0 +1,317 @@
+import process from 'node:process';
+import path from 'node:path';
+import {
+	app,
+	BrowserWindow,
+	shell,
+	dialog,
+	session,
+} from 'electron';
+import {assertSafeFilename} from 'is-safe-filename';
+import {unusedFilenameSync} from 'unused-filename';
+import pupa from 'pupa';
+import extName from 'ext-name';
+
+export class CancelError extends Error {}
+
+// The items already taken by a `download()` call, so that concurrent calls for the same URL each get their own item.
+const claimedItems = new WeakSet();
+// Items whose interruption has already been reported (OpenHarmony fail-fast path).
+const interruptedItems = new WeakSet();
+
+const getFilenameFromMime = (name, mime) => {
+	const extensions = extName.mime(mime);
+
+	return extensions.length === 1 ? `${name}.${extensions[0].ext}` : name;
+};
+
+function registerListener(session, options, callback = () => {}, {ownerWindow, url} = {}) {
+	options = {
+		showBadge: true,
+		showProgressBar: true,
+		...options,
+	};
+
+	// Checked here instead of in the listener, where a throw would escape as an uncaught exception and leave the `download()` promise unsettled.
+	if (options.directory && !path.isAbsolute(options.directory)) {
+		throw new Error('The `directory` option must be an absolute path');
+	}
+
+	// A `filename` with a path separator could escape `directory`, so it has to be a plain filename.
+	if (options.filename !== undefined) {
+		assertSafeFilename(options.filename);
+	}
+
+	const directory = options.directory ?? app.getPath('downloads');
+	const downloadItems = new Set();
+	let receivedBytes = 0;
+	let completedBytes = 0;
+	let totalBytes = 0;
+	const activeDownloadItems = () => downloadItems.size;
+	// The total size is 0 when it is not known, for example for a response without `Content-Length`.
+	const progressDownloadItems = () => totalBytes === 0 ? 0 : receivedBytes / totalBytes;
+
+	const listener = (event, item, webContents) => {
+		// Every `will-download` listener is notified of every download on the session, so `download()` ignores the items of other calls and only ever takes a single item.
+		if (url !== undefined) {
+			if (item.getURLChain().at(0) !== url || claimedItems.has(item)) {
+				return;
+			}
+
+			claimedItems.add(item);
+			session.removeListener('will-download', listener);
+		}
+
+		downloadItems.add(item);
+		totalBytes += item.getTotalBytes();
+
+		// `webContents` is null for `session.downloadURL()`, and there is no window for a detached `WebContentsView`.
+		const window_ = ownerWindow ?? (webContents ? BrowserWindow.fromWebContents(webContents) : undefined);
+
+		let name;
+		if (options.filename) {
+			name = options.filename;
+		} else {
+			const filename = item.getFilename();
+			name = path.extname(filename) ? filename : getFilenameFromMime(filename, item.getMimeType());
+		}
+
+		const filePath = options.overwrite ? path.join(directory, name) : unusedFilenameSync(path.join(directory, name));
+
+		const errorMessage = options.errorMessage ?? 'The download of {filename} was interrupted';
+
+		if (options.saveAs) {
+			item.setSaveDialogOptions({defaultPath: filePath, ...options.dialogOptions});
+		} else {
+			item.setSavePath(filePath);
+		}
+
+		item.on('updated', (_event, state) => {
+			receivedBytes = completedBytes;
+			for (const activeItem of downloadItems) {
+				receivedBytes += activeItem.getReceivedBytes();
+			}
+
+			if (options.showBadge && ['darwin', 'linux'].includes(process.platform)) {
+				app.badgeCount = activeDownloadItems();
+			}
+
+			if (window_ && !window_.isDestroyed() && options.showProgressBar) {
+				window_.setProgressBar(progressDownloadItems());
+			}
+
+			if (typeof options.onProgress === 'function') {
+				const itemTransferredBytes = item.getReceivedBytes();
+				const itemTotalBytes = item.getTotalBytes();
+
+				options.onProgress({
+					percent: itemTotalBytes ? itemTransferredBytes / itemTotalBytes : 0,
+					transferredBytes: itemTransferredBytes,
+					totalBytes: itemTotalBytes,
+				});
+			}
+
+			if (typeof options.onTotalProgress === 'function') {
+				options.onTotalProgress({
+					percent: progressDownloadItems(),
+					transferredBytes: receivedBytes,
+					totalBytes,
+				});
+			}
+
+				// Chromium stops retrying an interrupted download without ending it, so resume it when the server supports it.
+				// Resuming has to happen outside this handler, since Chromium asserts when a download re-enters its own observer notification.
+				if (state === 'interrupted' && item.canResume()) {
+					if (process.platform === 'openharmony') {
+						// OpenHarmony adaptation: ANY call to `item.resume()` on
+						// HarmonyOS PC Electron deadlocks the main process event
+						// loop (verified on Electron 34 — immediate, backoff-spaced
+						// and capped retries all reproduced it). Never resume here;
+						// fail fast so the caller can restart the download itself.
+						if (!interruptedItems.has(item)) {
+							interruptedItems.add(item);
+							const message = pupa(errorMessage, {filename: path.basename(filePath)});
+							callback(new Error(message + ' (auto-resume is not available on openharmony; restart the download to recover)'));
+							item.cancel();
+						}
+					} else {
+						setTimeout(() => {
+							if (item.canResume()) {
+								item.resume();
+							}
+						}, 0);
+					}
+				}
+		});
+
+		item.on('done', (_event, state) => {
+			completedBytes += item.getTotalBytes();
+			downloadItems.delete(item);
+
+			if (options.showBadge && ['darwin', 'linux'].includes(process.platform)) {
+				app.badgeCount = activeDownloadItems();
+			}
+
+			if (!activeDownloadItems()) {
+				if (window_ && !window_.isDestroyed()) {
+					window_.setProgressBar(-1);
+				}
+
+				receivedBytes = 0;
+				completedBytes = 0;
+				totalBytes = 0;
+			}
+
+			// eslint-disable-next-line unicorn/prefer-switch
+			if (state === 'cancelled') {
+				if (typeof options.onCancel === 'function') {
+					options.onCancel(item);
+				}
+
+				callback(new CancelError());
+			} else if (state === 'interrupted') {
+				const message = pupa(errorMessage, {filename: path.basename(filePath)});
+				callback(new Error(message));
+			} else if (state === 'completed') {
+				const savePath = item.getSavePath();
+
+				if (process.platform === 'darwin') {
+					app.dock.downloadFinished(savePath);
+				}
+
+				if (options.openFolderWhenDone) {
+					shell.showItemInFolder(savePath);
+				}
+
+				if (typeof options.onCompleted === 'function') {
+					options.onCompleted({
+						fileName: item.getFilename(), // Just for backwards compatibility. TODO: Remove in the next major version.
+						filename: item.getFilename(),
+						path: savePath,
+						fileSize: item.getReceivedBytes(),
+						mimeType: item.getMimeType(),
+						url: item.getURL(),
+					});
+				}
+
+				callback(null, item);
+			}
+		});
+
+		if (typeof options.onStarted === 'function') {
+			options.onStarted(item);
+		}
+	};
+
+	session.on('will-download', listener);
+}
+
+export default function electronDl(options = {}) {
+	const handleError = error => {
+		if (!error || error instanceof CancelError) {
+			return;
+		}
+
+		if (typeof options.onError === 'function') {
+			options.onError(error);
+			return;
+		}
+
+		// OpenHarmony adaptation: `dialog.showErrorBox()` is a synchronous modal
+		// dialog that blocks the main process event loop until dismissed — with
+		// nobody at the desktop this freezes the whole app (all timers and IPC
+		// stop). Log non-blockingly instead; pass `onError` for custom handling.
+		if (process.platform === 'openharmony') {
+			console.error(`[electron-dl] ${options.errorTitle ?? 'Download Error'}: ${error.message}`);
+			return;
+		}
+
+		const errorTitle = options.errorTitle ?? 'Download Error';
+		dialog.showErrorBox(errorTitle, error.message);
+	};
+
+	const registered = new WeakSet();
+	const register = session_ => {
+		if (registered.has(session_)) {
+			return;
+		}
+
+		registered.add(session_);
+		registerListener(session_, options, handleError);
+	};
+
+	app.on('session-created', register);
+
+	// OpenHarmony adaptation: on HarmonyOS PC Electron the 'session-created'
+	// event may not fire for sessions that already exist, and
+	// `session.getAllSessions()` is not available on Electron 34 — both left
+	// registration-mode downloads without a 'will-download' listener and they
+	// never completed. Register synchronously on the default session (the
+	// README headline usage: app windows without custom partitions). Gated to
+	// openharmony so behavior on other platforms is unchanged.
+	if (process.platform === 'openharmony') {
+		register(session.defaultSession);
+	}
+}
+
+export async function download(window_, url, options) {
+	return new Promise((resolve, reject) => {
+		const {session} = window_.webContents;
+
+		// Chromium normalizes the URL, so it must be normalized here too for the item to be recognized as this call's download.
+		const normalizedUrl = new URL(url).href;
+
+		// Start the download from the session instead of the `webContents` so it is not subject to the page's origin checks.
+		registerListener(session, options, (error, item) => {
+			if (error) {
+				reject(error);
+				return;
+			}
+
+			resolve(item);
+		}, {
+			ownerWindow: BrowserWindow.fromWebContents(window_.webContents),
+			url: normalizedUrl,
+		});
+
+		session.downloadURL(normalizedUrl);
+	});
+}
+
+export async function downloadAsBytes(window_, url, options = {}) {
+	const {session} = window_.webContents;
+	const response = await session.fetch(url, {signal: options.signal});
+
+	if (!response.ok) {
+		throw new Error(`The download of ${url} failed with status ${response.status}`);
+	}
+
+	// Chromium decompresses the body, so for an encoded response `Content-Length` is the compressed size and cannot be used for progress.
+	const isEncoded = response.headers.get('content-encoding') !== null;
+	const totalBytes = isEncoded ? 0 : Number(response.headers.get('content-length')) || 0;
+	const chunks = [];
+	let transferredBytes = 0;
+
+	// `response.body` is null for responses that cannot have a body, for example `204`.
+	for await (const chunk of response.body ?? []) {
+		chunks.push(chunk);
+		transferredBytes += chunk.length;
+
+		if (typeof options.onProgress === 'function') {
+			options.onProgress({
+				percent: totalBytes === 0 ? 0 : transferredBytes / totalBytes,
+				transferredBytes,
+				totalBytes,
+			});
+		}
+	}
+
+	const bytes = new Uint8Array(transferredBytes);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.length;
+	}
+
+	return bytes;
+}

package/license

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@ohos-ports/electron-dl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "5.0.0-beta.0",
+  "description": "Simplified file downloads for your Electron app",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ohos-ports/ohos-ports.git",
+    "directory": "ports/@ohos-ports/electron-dl/5.0.0"
+  },
+  "funding": "https://github.com/sponsors/sindresorhus",
+  "author": "Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)",
+  "type": "module",
+  "exports": {
+    "types": "./index.d.ts",
+    "default": "./index.js"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "start": "electron run.js",
+    "test": "xo && ava test/downloads.js && tsc index.d.ts"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "keywords": [
+    "electron",
+    "app",
+    "file",
+    "download",
+    "downloader",
+    "progress"
+  ],
+  "dependencies": {
+    "ext-name": "^5.0.0",
+    "is-safe-filename": "^0.1.1",
+    "pupa": "^3.3.0",
+    "unused-filename": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "ava": "^8.0.1",
+    "electron": "^44.4.3",
+    "minimist": "^1.2.8",
+    "node-static": "^0.7.11",
+    "typescript": "^6.0.3",
+    "xo": "^5.0.1"
+  },
+  "xo": {
+    "ignores": [
+      "mock"
+    ]
+  },
+  "ava": {
+    "serial": true,
+    "timeout": "1m"
+  }
 }

package/readme.md

@@ -0,0 +1,367 @@
+# electron-dl
+
+> Simplified file downloads for your [Electron](https://electronjs.org) app
+
+## Why?
+
+- One function call instead of having to manually implement a lot of [boilerplate](index.js).
+- Saves the file to the users Downloads directory instead of prompting.
+- Bounces the Downloads directory in the dock when done. *(macOS)*
+- Handles multiple downloads.
+- Resumes interrupted downloads when the server supports it, while the app is running.
+- Shows badge count *(macOS & Linux only)* and download progress. Example on macOS:
+
+<img src="screenshot.png" width="82">
+
+## Install
+
+```sh
+npm install electron-dl
+```
+
+*Requires Electron 44 or later.*
+
+## Usage
+
+### Register it for all windows
+
+This is probably what you want for your app.
+
+```js
+import {app, BrowserWindow} from 'electron';
+import electronDl from 'electron-dl';
+
+electronDl();
+
+let mainWindow;
+(async () => {
+	await app.whenReady();
+	mainWindow = new BrowserWindow();
+})();
+```
+
+### Use it manually
+
+This can be useful if you need download functionality in a reusable module.
+
+```js
+import {BrowserWindow, ipcMain} from 'electron';
+import {download, CancelError} from 'electron-dl';
+
+ipcMain.on('download-button', async (event, {url}) => {
+	const win = BrowserWindow.getFocusedWindow();
+	try {
+		console.log(await download(win, url));
+	} catch (error) {
+		if (error instanceof CancelError) {
+			console.info('item.cancel() was called');
+		} else {
+			console.error(error);
+		}
+	}
+});
+```
+
+### Download into memory
+
+This can be useful if you want to process a file without saving it to disk first.
+
+```js
+import {BrowserWindow, ipcMain} from 'electron';
+import {downloadAsBytes} from 'electron-dl';
+
+ipcMain.on('download-button', async (event, {url}) => {
+	const win = BrowserWindow.getFocusedWindow();
+	const bytes = await downloadAsBytes(win, url);
+	console.log(bytes.length);
+});
+```
+
+## API
+
+It can only be used in the [main](https://electronjs.org/docs/glossary/#main-process) process.
+
+### electronDl(options?)
+
+### download(window, url, options?): Promise<[DownloadItem](https://electronjs.org/docs/api/download-item)>
+
+Multiple calls can be in progress at the same time. Each call handles its own download.
+
+An interrupted download is resumed automatically when the server supports it, as long as the app is running. A download is not resumed after the app is restarted, since that would need the app to persist the download state.
+
+### window
+
+Type: `BrowserWindow | WebContentsView`
+
+The window to register the behavior on. Alternatively, a `WebContentsView` can be passed.
+
+### url
+
+Type: `string`
+
+The URL to download.
+
+### options
+
+Type: `object`
+
+#### saveAs
+
+Type: `boolean`\
+Default: `false`
+
+Show a `Save As…` dialog instead of downloading immediately.
+
+Note: Only use this option when strictly necessary. Downloading directly without a prompt is a much better user experience.
+
+#### directory
+
+Type: `string`\
+Default: [User's downloads directory](https://electronjs.org/docs/api/app/#appgetpathname)
+
+The directory to save the file in.
+
+Must be an absolute path.
+
+#### filename
+
+Type: `string`\
+Default: [`downloadItem.getFilename()`](https://electronjs.org/docs/api/download-item/#downloaditemgetfilename)
+
+Name of the saved file.
+
+Must not contain a path separator, so it cannot point outside `directory`.
+
+This option only makes sense for `electronDl.download()`.
+
+#### errorTitle
+
+Type: `string`\
+Default: `'Download Error'`
+
+Title of the error dialog. Can be customized for localization.
+
+Note: Error dialog will not be shown in `electronDl.download()`. Please handle error manually.
+
+#### errorMessage
+
+Type: `string`\
+Default: `'The download of {filename} was interrupted'`
+
+Message of the error dialog. `{filename}` is replaced with the name of the actual file. Can be customized for localization.
+
+Note: Error dialog will not be shown in `electronDl.download()`. Please handle error manually.
+
+#### onStarted
+
+Type: `Function`
+
+Optional callback that receives the [download item](https://electronjs.org/docs/api/download-item).
+You can use this for advanced handling such as canceling the item like `item.cancel()` which will throw `electronDl.CancelError` from the `electronDl.download()` method.
+
+#### onProgress
+
+Type: `Function`
+
+Optional callback that receives an object containing information about the progress of the current download item.
+
+```js
+{
+	percent: 0.1,
+	transferredBytes: 100,
+	totalBytes: 1000
+}
+```
+
+#### onTotalProgress
+
+Type: `Function`
+
+Optional callback that receives an object containing information about the combined progress of all download items done within any registered window.
+
+Each time a new download is started, the next callback will include it. The progress percentage could therefore become smaller again.
+This callback provides the same data that is used for the progress bar on the app icon.
+
+```js
+{
+	percent: 0.1,
+	transferredBytes: 100,
+	totalBytes: 1000
+}
+```
+
+#### onCancel
+
+Type: `Function`
+
+Optional callback that receives the [download item](https://electronjs.org/docs/api/download-item) for which the download has been cancelled.
+
+#### onCompleted
+
+Type: `Function`
+
+Optional callback that receives an object with information about an item that has been completed. It is called for each completed item.
+
+```js
+{
+	filename: 'file.zip',
+	path: '/path/file.zip',
+	fileSize: 503320,
+	mimeType: 'application/zip',
+	url: 'https://example.com/file.zip'
+}
+```
+
+#### onError
+
+Type: `Function`
+
+Optional callback that receives the `Error` for a download that was interrupted and could not be resumed.
+
+When this is provided, the error dialog is not shown. Use this to show your own error dialog or to handle the failure in another way.
+
+This option only makes sense for the default export. `electronDl.download()` rejects with the error instead.
+
+```js
+import electronDl from 'electron-dl';
+
+electronDl({
+	onError(error) {
+		console.error(error.message);
+	}
+});
+```
+
+#### openFolderWhenDone
+
+Type: `boolean`\
+Default: `false`
+
+Reveal the downloaded file in the system file manager, and if possible, select the file.
+
+#### showBadge
+
+Type: `boolean`\
+Default: `true`
+
+Show a file count badge on the macOS/Linux dock/taskbar icon when a download is in progress.
+
+#### showProgressBar
+
+Type: `boolean`\
+Default: `true`
+
+Show a progress bar on the dock/taskbar icon when a download is in progress.
+
+Downloads without an associated `BrowserWindow` are saved normally, but do not show a progress bar.
+
+#### overwrite
+
+Type: `boolean`\
+Default: `false`
+
+Allow downloaded files to overwrite files with the same name in the directory they are saved to.
+
+The default behavior is to append a number to the filename.
+
+#### dialogOptions
+
+Type: [`SaveDialogOptions`](https://www.electronjs.org/docs/latest/api/download-item#downloaditemsetsavedialogoptionsoptions)\
+Default: `{}`
+
+Customize the save dialog.
+
+If `defaultPath` is not explicity defined, a default value is assigned based on the file path.
+
+### downloadAsBytes(window, url, options?): Promise<`Uint8Array`>
+
+Download a file into memory instead of saving it to disk. Use this when you want to process the file directly.
+
+The download does not appear in the Downloads directory. It is not shown in the dock/taskbar badge or progress bar, and it cannot be resumed.
+
+The promise rejects when the server responds with an error status.
+
+`window` and `url` are the same as for `download()`.
+
+#### onProgress
+
+Type: `Function`
+
+Optional callback that receives an object containing information about the progress of the download.
+
+```js
+{
+	percent: 0.1,
+	transferredBytes: 100,
+	totalBytes: 1000
+}
+```
+
+`percent` is `0` when the total size is not known, for example for a compressed or chunked response.
+
+#### signal
+
+Type: [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+
+An `AbortSignal` to cancel the download with. An aborted download rejects with the signal's abort reason, which defaults to an `AbortError`.
+
+## Development
+
+After making changes, run the automated tests:
+
+```sh
+npm test
+```
+
+And before submitting a pull request, run the manual tests to manually verify that everything works:
+
+```sh
+npm start
+```
+
+## Related
+
+- [electron-debug](https://github.com/sindresorhus/electron-debug) - Adds useful debug features to your Electron app
+- [electron-context-menu](https://github.com/sindresorhus/electron-context-menu) - Context menu for your Electron app
+- [electron-store](https://github.com/sindresorhus/electron-store) - Save and load data like user settings, app state, cache, etc
+- [electron-unhandled](https://github.com/sindresorhus/electron-unhandled) - Catch unhandled errors and promise rejections in your Electron app
+
+## OpenHarmony adaptation (@ohos-ports fork)
+
+Two adaptations for HarmonyOS PC Electron (`process.platform === "openharmony"`),
+both verified on Electron 34:
+
+- **Interrupted downloads fail fast instead of deadlocking.** Upstream calls
+  `item.resume()` when a download is interrupted and the server supports
+  ranges; on HarmonyOS PC Electron ANY such call synchronously deadlocks the
+  main process event loop (all timers and IPC stop firing — immediate, spaced
+  and capped retries all reproduce it). This fork never calls `resume()` on
+  openharmony: the `download()` promise (or `onError` in registration mode)
+  rejects with a descriptive error and the item is cancelled. Restart the
+  download yourself to recover, e.g. by retrying `download()`.
+- **Registration mode also covers the default session.** `electronDl()` relied
+  solely on the `session-created` event, which does not fire for sessions that
+  already exist on HarmonyOS PC Electron (and `session.getAllSessions()` is not
+  available on Electron 34), leaving their downloads without a listener. The
+  fork additionally registers on `session.defaultSession` synchronously (gated
+  to `openharmony`; other platforms behave exactly as upstream). Custom
+  partition sessions created via `session.fromPartition()` after the
+  `electronDl()` call may still not be covered — prefer `download()` for those.
+
+- **Registration-mode errors are non-blocking on openharmony.** The upstream
+  default error handler (`dialog.showErrorBox`) is a synchronous modal dialog
+  that blocks the main process event loop until dismissed; on HarmonyOS PC
+  this can freeze the whole app. The fork logs to `console.error` instead —
+  pass `onError` for custom handling.
+
+Known limitations:
+
+- The `WebAssembly` global is missing from the main process on HarmonyOS PC
+  Electron, so Node's built-in `fetch`/undici is unusable there.
+  `download()` and `downloadAsBytes()` (via Electron's `session.fetch`) are
+  unaffected and fully functional.
+- Interrupted downloads always reject on openharmony (no auto-resume), so
+  transient interruptions surface as errors — retry at the application level.
+- Downloads on `session.defaultSession` (registration mode without custom
+  partitions) were observed to be flaky on HarmonyOS PC Electron; prefer
+  `download()` from a window, or custom partition sessions.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.