import Files from '@pageproof/sdk/src/api/Files.js'

public class | source

Files

Extends:

API → Files

Method Summary

Public Methods
public	details(fileId: string): Promise<File> Loads the details of a file.
public	download(options: object \| string): Promise<Blob\|Buffer\|null> Downloads a file.
public	upload(options: object): Promise<File> Upload a file.

Inherited Summary

From class API
public	client: PageProof

Public Methods

public details(fileId: string): Promise<File> source

Loads the details of a file.

Params:

Name	Type	Attribute	Description
fileId	string		The file identifier (16 characters, begins with F)

Return:

Promise<File>

public download(options: object | string): Promise<Blob|Buffer|null> source

Downloads a file.

Depending on the execution environment, this method resolves different types of values. For browser environments the method resolves a Blob, and for Node.js it resolves a Buffer - both containing the contents of the original file.

This method throws an error if; the owner of a proof has specified the file not to be downloadable, or in the case of file attachments/snapshots if you're not an owner of the proof, or if the file is still uploading/errored.

Params:

Name	Type	Attribute	Description
options	object \| string		The options or file id
options.fileId	string		The file id
options.onData	function	optional	An optional callback to override how the decrypted file blocks are handled. You will want to override this method when dealing with large files (especially in Node.js, as the default behaviour resorts to an in-memory Buffer to store the file's content). The callback is invoked with a Blob or Buffer (depending on the runtime environment) containing the next slice of data. The callback is always invoked in order (with the second argument being the index, and third being how many pieces make up the whole file). If you provide this option, the Promise will resolve with a `null`.
options.onProgress	function	optional	A callback for tracking the download percentage

Return:

Promise<Blob|Buffer|null>

Example:

const fs = require('fs');
const Bluebird = require('bluebird');
 
Bluebird.promisifyAll(fs); // Allows for `fs.appendFileAsync`
 
const client = new PageProof({ ... });
 
const filename = __dirname + '/download.pdf';
await client.files.download({
  fileId: 'F8TVFW83YIMMC4TA',
  async onData(data, index, length) {
    await fs.appendFileAsync(filename, data);
  }
});

const blob = await client.files.download('F8TVFW83YIMMC4TA');
// or
const blob = await client.files.download({
  fileId: 'F8TVFW83YIMMC4TA',
});

public upload(options: object): Promise<File> source

Upload a file.

By default this method resolves as soon as the server has created an empty resource for the SDK to stream to. This means that the actual file encryption, chunking & uploading happens independently to the main Promise. This technique is recommended, however can still be disabled by setting the async option to false.

In PageProof, Files are separate entities until attached to another entity (like a Proof, or Comment). For this reason, it's recommended that you attach the file as soon as possible.

File names do not have to be unique, you can upload as many files with the name "logo.png" as you like - as we use file IDs to identify unique files. The name name is displayed in the PageProof frontend to give users more context.

The download option describes whether other user's in PageProof are allowed to download the file.

Params:

Name	Type	Attribute	Description
options	object
options.name	string		The file name (including the extension)
options.contents	Blob \| File \| Buffer		The file's contents
options.download	boolean	optional default: false	Whether the file can be downloaded by reviewers
options.async	boolean	optional default: true	Whether to upload the file independently of the Promise
options.onProgress	function	optional	A callback for tracking the upload percentage

Return:

Promise<File>

Example:

Uploading a file from an <input /> element (Browser)

// Assume there's an <input /> element on the page for a user to select a file
const input = document.querySelector('input[name="file"]');
input.onchange = async () => {
  const file = input.files[0]; // Get the File object from the input element
  await client.files.upload({
    name: file.name, // Use the file's name
    contents: file,
    onProgress: percent => {
      // Assume there's a <progress /> element to display some progress to the user
      const progressBar = document.querySelector('#progress-bar');
      progressBar.value = percent;
    },
  });
};

Uploading a file and waiting for it to complete (Browser)

const file = await client.files.upload({
  name: 'example.pdf',
  contents: new Blob([ <omitted> ]),
  async: false,
});
console.log(`The file has been uploaded! It's ID is ${file.id}.`);

Uploading a file & tracking it's progress (Node.js)

const file = await client.files.upload({
  name: 'logo.png',
  contents: fs.readFileSync(__dirname + '/logo.png'),
  onProgress: percent => {
    console.log(`Uploading... ${percent}%`);
  }
});
console.log(`The file has begun uploading... It's ID is ${file.id}.`);