Web Uploader API Reference

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

Constructor

import { Uploader } from "@masvio/uploader";

const uploader = new Uploader(packageID, packageToken, apiURL);

Parameter	Type	Description
packageID	string	The ID of the Package to upload files to. Obtained when creating a Portal Package or a Team Package via the Packages API.
packageToken	string	The authorized JWT token for the Package, returned at Package creation time.
apiURL	string	The base URL of the MASV API. Use https://api.massive.app for production.

Methods

addFiles

Adds one or more files to the upload queue. Uploading begins automatically once the first file is processed.

uploader.addFiles(file1, file2, ...fileN);

You can also spread an array:

const files = [
  { id: "file-0", file: fileObj, path: "" },
  { id: "file-1", file: fileObj2, path: "subfolder/" },
];

uploader.addFiles(...files);

Each argument must be a MasvFile object.

start

Resumes the upload after it has been paused. Only required if the uploader was previously paused with pause().

uploader.start();

pause

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

uploader.pause();

cancel

Cancels the upload. Stops all in-flight transfers and prevents further uploads.

uploader.cancel();

finalize

Finalizes the upload. Signals that all files have been added and the Package is ready for delivery.

uploader.finalize();

terminate

Terminates the uploader instance and all of its workers. Use this to clean up resources when the uploader is no longer needed.

uploader.terminate();

getPerformanceStats

Returns statistics about the uploader’s performance, including throughput and transfer metrics.

const stats = uploader.getPerformanceStats();

Data types

MasvFile

The file object format expected by addFiles().

Property	Type	Description
id	string	A unique identifier for this file upload.
file	File	The browser File object.
path	string	The file path used to preserve folder structure on the receiving end. Use "" for flat uploads.

Events

Subscribe to events using the on() method. You can listen for a specific event or delegate a handler for all events.

Listening for a specific event

uploader.on(Uploader.UploaderEvents.Progress, (event) => {
  console.log(event);
});

Delegating all events

const handlers = {
  [Uploader.UploaderEvents.Progress]: (e) => console.log("Progress:", e),
  [Uploader.UploaderEvents.Finished]: (e) => console.log("Done:", e),
};

uploader.on("emit", (event) => {
  if (event.name in handlers) {
    handlers[event.name](event);
  }
});

Event payload

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 table below).
time	number	A Unix timestamp indicating when the event was fired.
target	object	The uploader module that fired the event.
data	object	Event-specific data relevant to the event type.

Event list

Constant	String Value	Description
Created	uploader:create	The uploader instance is initialized.
Start	upload:start	The uploader begins uploading data — either at the start of the upload or after a pause.
FileQueued	upload:file_queued	A file is queued for upload.
Progress	upload:progress	Data is successfully sent. Use this to update progress indicators.
Chunk	upload:chunk	A chunk of a file has finished uploading.
File	upload:file	All chunks for a file have finished uploading.
Finalize	upload:finalize	The uploader has finalized a file upload.
Error	upload:error	An error occurred during an upload request.
Finished	upload:finish	The uploader has finished uploading all files.
Abort	upload:abort	An upload is aborted, typically when the uploader is paused.
Retry	upload:retry	The uploader is retrying a request, usually due to a network issue.
File Unreadable	upload:file_unreadable	The browser is unable to read one of the files in the Package.
Stalled	upload:stalled	No upload progress has been reported for at least 1 minute.

Events are accessed via the Uploader.UploaderEvents enum:

Uploader.UploaderEvents.Progress   // "upload:progress"
Uploader.UploaderEvents.Finished   // "upload:finish"
Uploader.UploaderEvents.Error      // "upload:error"
// ... etc.