Web Downloader API Reference

This page documents the full API surface of the MASV Web Downloader SDK (@masvio/downloader). For a guided walkthrough, see the Getting Started guide.

Constructor

import { Downloader } from "@masvio/downloader";

const downloader = new Downloader(masvLink, linkPassword, userToken, apiBaseURL, chunkSize);

Parameter	Type	Required	Description
`masvLink`	`string`	Yes	The download link of the Package being downloaded. Obtained from the Package download page. After instantiation, the downloader can download contents from this Package only. A new downloader must be instantiated for each download attempt (not including pause and resume).
`linkPassword`	`string`	Conditional	The password for the MASV download link. Required only if a password has been set for the link.
`userToken`	`string`	Conditional	A MASV user token used for download links that require user authentication. Required only if user authentication is enabled for the link.
`apiBaseURL`	`string`	No	The base URL of the MASV API. Default: `https://api.massive.app`.
`chunkSize`	`number`	No	The size of each download chunk in bytes. Default: `104857600` (100 MiB).

Methods

initialize

Required for bootstrapping the Downloader instance. Must be called before start(). Implicitly calls loadFiles() to retrieve the file list from the download link.

await downloader.initialize();

start

Starts the download or resumes a paused download.

await downloader.start(directoryHandle, fileList);

Parameter	Type	Required	Description
`directoryHandle`	`FileSystemDirectoryHandle`	Yes	The directory where the Package contents will be downloaded to. Obtained via `showDirectoryPicker()`.
`fileList`	`BaseFile[]`	No	An array of files to download. If omitted, all files from the download link are downloaded.

pause

Pauses the download. In-flight chunk requests are aborted. Call start() to resume.

downloader.pause();

retry

Resumes the download and retries any failed files. Only valid when the downloader is in the PartialFinished state.

await downloader.retry();

cancel

Cancels the download. The downloader cannot perform any further downloads after cancellation.

downloader.cancel();

terminate

Terminates the downloader and all of its workers. The downloader cannot perform any other actions after termination. Use this to clean up resources when the downloader is no longer needed.

downloader.terminate();

loadFiles

Retrieves all files from the download link the Downloader is instantiated with. Returns an array of BaseFile objects.

const files = await downloader.loadFiles();

Interfaces

BaseFile

Represents a file available for download from the Package.

Property	Type	Description
`id`	`string`	Unique identifier for the file.
`kind`	`string`	The file type. Possible values: `file`, `directory`, `metadata`, `zip_windows`, `zip_mac`.
`last_modified`	`string`	The last modified timestamp of the file.
`name`	`string`	The file name.
`path`	`string`	The relative file path, used to preserve folder structures. May be `undefined`.
`size`	`number`	The size of the file in bytes. May be `undefined`.
`virus_detected`	`boolean`	Indicates whether a virus has been detected. Files with this field set to `true` are not downloaded and the downloader emits a `FileErrored` event instead.
`completed`	`boolean`	Indicates that the file is ready for download. Only relevant for MASV-generated zip files.

EventPayloads

Every event callback receives an object with the following structure:

Property	Type	Description
`event`	`string`	The event name (one of the values listed in the events table).
`data`	`object`	Event-specific data relevant to the event type.
`time`	`number`	A Unix timestamp indicating when the event was fired.
`target`	`object`	The downloader module that fired the event.

PerformanceResults

Performance statistics returned in Progress, Finished, PartialFinished, Error, and Retry event payloads.

Property	Type	Description
`duration`	`number`	Milliseconds elapsed since the download started.
`speed`	`number`	Average download speed calculated from total progress and duration. Measured in bits per second.
`instant`	`number`	Most recent download speed measurement. Measured in bits per second.
`moving`	`number`	Download speed over a recent period (short-term average). Measured in bits per second.
`total`	`number`	Size of the entire download in bytes.
`progress`	`number`	Total bytes processed from network requests. May decrease after pausing since unwritten data is discarded and some progress is lost.
`chunkProgress`	`number`	Total bytes written to disk. May decrease when a file fails and partial chunk progress is lost.
`fileProgress`	`number`	Total bytes from fully downloaded files.
`totalFiles`	`number`	Number of files included in the transfer.
`finalizedFiles`	`number`	Number of successfully downloaded files.

Events

Subscribe to events using the on() method. Attach callbacks before calling start().

Listening for events

downloader.on(Downloader.DownloaderEvents.Progress, ({ data }) => {
  console.log("Progress:", data.performanceStats);
});

States

The downloader emits state change events as it transitions through the download lifecycle:

Constant	Description
`Downloading`	The downloader is actively downloading files.
`Paused`	The download has been paused.
`Cancelled`	The download has been cancelled.
`Terminated`	The downloader has been terminated.

States are accessed via the Downloader.States enum:

downloader.on(Downloader.States.Downloading, () => {
  console.log("Downloading");
});

Event list

Constant	String Value	Data	Description
`Abort`	`download:abort`	`fileId: string`	The download has been aborted after pausing or cancelling the transfer.
`Error`	`download:error`	`performanceStats: PerformanceResults; error: Error`	An error has occurred with the downloader. The download cannot continue.
`FileDownloaded`	`download:file-downloaded`	`fileId: string`	A file has been successfully downloaded.
`FileErrored`	`download:file-errored`	`fileId: string; error: Error`	An error has occurred downloading a specific file. Errored files are automatically skipped, allowing the download to continue.
`FileQueued`	`download:file-queued`	`fileId: string`	A file has been queued for download.
`Finished`	`download:finish`	`performanceStats: PerformanceResults`	All files have been successfully downloaded.
`ParentDirectoryCreated`	`download:parent-directory-created`	`parentDirectoryName: string`	A parent directory named after the Package has been created. This happens before any files are downloaded.
`PartialFinished`	`download:partial-finish`	`performanceStats: PerformanceResults; failedFiles: BaseFile[]`	One or more files failed during download. The affected files were skipped and the rest of the download completed successfully. Errored files can be retried with `retry()`.
`Progress`	`download:progress`	`performanceStats: PerformanceResults`	Download progress report.
`Retry`	`download:retry`	`performanceStats: PerformanceResults; error: Error`	The downloader is retrying a request, usually due to a network issue.

Events are accessed via the Downloader.DownloaderEvents enum:

Downloader.DownloaderEvents.Progress   // "download:progress"
Downloader.DownloaderEvents.Finished   // "download:finish"
Downloader.DownloaderEvents.Error      // "download:error"
// ... etc.