Criptext Files SDK

Features

• Files: Stores and Retrieves files from Criptext
• Uploads: Handles file uploads through chunks
• Downloads: Handles file downloads through chunks
• Queueing: Queue files to efficiently process one file at a time

Examples

• Live Demo: A live demo is included within the repo, but first you need to generate the JS file:

yarn build

Getting Started

import FileManager from 'criptext-files-sdk'

Or include the generated JS in your project and import it

<script src='../dist/main.js'>
</script>

Create a FileManager and initialize it

const fileManager = new FileManager();

fileManager.init({
  app_id: 'eanocurdaonhdjhfa', 
  app_secret: 'yunsdhobsidjdad',
  max_requests: 5, 
  sandbox: false 
});

Or

const fileManager = new FileManager({
  app_id: 'eanocurdaonhdjhfa', 
  app_secret: 'yunsdhobsidjdad',
  max_requests: 5, 
  sandbox: false 
});

Or if you want to use a custom token (Bearer auth)

const fileManager = new FileManager({
  auth: 'Bearer', 
  auth_token: 'eyarnpcmgvrhgnaclshagpsrepnthniotamrviulvgcsohglsf',
  max_requests: 5, 
  sandbox: false 
});

| Param | Default | Type | Info | --- | --- | --- | --- | app_id | null | string | App Key used to access the server | app_secret | null | string | App Secret used to access the server | max_requests | 5 | number | number of simultaneous requests allowed for the sdk | sandbox | false | boolean | whether the skd connects to a testing server or not

Encryption and Decryption

You can pass 2 functions to encrypt and decrypt your files. A blob with a file slice will be passed as argument alongside a callback, when you finish processing the slice, you should use the callback and pass a blob as well for the file to be uploaded successfully.

fileManager.setCryptoInterfaces( (filetoken, blob, callback) => { //function to encrypt file
  //encrypt blob

  callback(newBlob);
}, (filetoken, blob, callback) => { //function to decrypt file
  //decrypt blob

  callback(newBlob);
})

| Param | Type | Info | --- | --- | --- | encryptionFunction | function | Invoked with (filetoken, blob, callback) | decryptionFunction | function | Invoked with (filetoken, blob, callback)

Uploading Files

Upload file

Adds the file to queue; it will be uploaded in background.

fileManager.uploadFile(file, chunkSize, (error, token) => {
  //Your Logic

  //If file is too large, you can find the max size allowed with the following code
  const maxSize = error.maxSize;

  //You can also check the status code
  const statusCode = error.status;
})

| Param | Type | Info | --- | --- | --- | file | File | File to be uploaded. You can obtain a File from an input field from type file | chunkSize | number | the chunkSize of your uploading file, default is 512KB | callback | function | function that will retrieve either an error or the file token. You must store this token because it's needed for any other operation for this file.

Pause upload

Allows you to pause an upload, whether it has begun or not.

fileManager.pauseUpload(token, (error) => {
  //Your Logic
})

| Param | Type | Info | --- | --- | --- | token | string | Token obtained in a previous upload request. | callback | function | function that will be executed after pause. An error, if any, will be passed as param.

Resume Upload

Resumes the file upload in queue. This doesn't mean the file will be uploaded immediately because another file might be being processed.

fileManager.resumeUpload(token, (error) => {
  //Your Logic
})

| Param | Type | Info | --- | --- | --- | token | string | Token obtained in a previous upload request. | callback | function | function that will be executed after resume. An error, if any, will be passed as param.

Cancel Upload

Pauses a file upload and removes it from the file list. A canceled file can't be resumed because it doesn't exist in the manager anymore.

fileManager.cancelUpload(token, (error) => {
  //Your Logic
})

| Param | Type | Info | --- | --- | --- | token | string | Token obtained in a previous upload request. | callback | function | function that will be executed after cancel. An error, if any, will be passed as param.

Download API

Download file

Adds the file to queue; it will be downloaded in background.

fileManager.downloadFile(token, (error) => {
  //Your Logic
})

| Param | Type | Info | --- | --- | --- | token | string | Token obtained in a previous upload request. | callback | function | function executed after the download request. An error, if any, will be passed as param.

Pause Download

Allows you to pause an upload, whether it has begun or not.

fileManager.pauseDownload(token, (error) => {
  //Your Logic
})

| Param | Type | Info | --- | --- | --- | token | string | Token obtained in a previous upload request. | callback | function | function that will be executed after pause. An error, if any, will be passed as param.

Resume Download

Resumes the file download in queue. This doesn't mean the file will be downloaded immediately because another file might be being processed.

fileManager.resumeDownload(token, (error) => {
  //Your Logic
})

| Param | Type | Info | --- | --- | --- | token | string | Token obtained in a previous upload request. | callback | function | function that will be executed after resume. An error, if any, will be passed as param.

Cancel Download

Pauses a file download and removes it from the file list. A canceled file can't be resumed because it doesn't exist in the manager anymore.

fileManager.cancelDownload(token, (error) => {
  //Your Logic
})

| Param | Type | Info | --- | --- | --- | token | string | Token obtained in a previous upload request. | callback | function | function that will be executed after cancel. An error, if any, will be passed as param.

Events

Every background process related to a file generates an event that is received by our file manager instance.

On File Progress

While the file is being uploaded or downloaded, it generates the following event.

fileManager.on(fileManager.Event.FILE_PROGRESS, (data) => {
  /* 
    data = {
      type: 'upload' | 'download',
      percentage: <int>,
      token: <string>,
      file: <object>
    }
  */

  // Your logic
})

On File Finish

When the file has successfully being upload/downloaded, this event will be triggered.

fileManager.on(fileManager.Event.FILE_FINISH, (data) => {
  /* 
    data = {
      type: 'upload' | 'download',
      url: <string>, // Only for type: 'download'
      token: <string>,
      file: <object>
    }
  */

  // Your logic
})

data.url is an url to a blob containing the downloaded file

On File Error

When an error occurred during file upload/download, this event will be triggered.

fileManager.on(fileManager.Event.FILE_ERROR, (data) => {
  /* 
    data = {
      type: 'upload' | 'download',
      error: <string>,
      token: <string>,
      file: <Object>
    }
  */

  // Your logic
})

Promises

Each of these functions return promises as well. To return a promise, don't pass a callback and that's it! Nevertheless, the events triggered by the fileManager should be handled as callbacks

fileManager.uploadFile(file, chunkSize).then( token => {
  //Your Logic
}).catch( error => {
  //Your Logic
})