Getting started

Dependency

npm install @tanker/filekit
# or...
yarn add @tanker/filekit

Import

import FileKit from '@tanker/filekit';
// or...
const { FileKit } = require('@tanker/filekit');

Constructor

const config = { appId: 'your-app-id' };
const fileKit = new FileKit(config);
Parameters Description
config: Object The configuration of this FileKit instance, containing:
config.appId: string The app ID

Session

The methods below allow you to start and stop a FileKit session.

Note

This documentation uses flow type annotations.

Start

Start a FileKit session, show the verification UI if needed and block until the user verifies their identity.

To verify the identity of a user, an email is sent by Tanker to their email address. This email contains a verification code that must be input in the UI displayed by FileKit when a verification is required.

function start(email: string, { identity: string, provisionalIdentity?: string }) : Promise<void>
Parameters Description
email: string The email address used to verify the user's identity
identity: string The Tanker identity of the given user (generated by @tanker/identity)
provisionalIdentity?: string A Tanker provisional identity that should be claimed by the user (generated by @tanker/identity). It only needs to be verified once and will be ignored if given again. (optional)
Returns
Promise The promise is fulfilled once the user has verified their identity
Throws Description
InvalidArgument The provided identity is invalid
PreconditionFailed The FileKit session has already been started
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable

StartDisposableSession

Start a disposable, one time session. The user does not have to verify their identity as it is discarded once the FileKit Session is stopped.

Disposable sessions can be used to upload files without requiring the user to authenticate.

function startDisposableSession({ identity: string }) : Promise<void>
Parameters Description
identity: string A Tanker identity (generated by @tanker/identity or @tanker/fake-authentication) with a random userID
Returns
Promise The promise is fulfilled once the stop operation is done
Throws Description
InvalidArgument The provided identity is invalid
PreconditionFailed The FileKit session has already been started
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable

Stop

Stop the current FileKit Session.

function stop(): Promise<void>
Returns
Promise The promise is fulfilled once the stop operation is done

Upload & Download

The methods below allow you to upload and download files. These files are encrypted before upload and decrypted after download.

Note

This documentation uses flow type annotations.

Upload

Encrypt and upload a file.

type FileId = string;
type Data = ArrayBuffer | Buffer | Blob | File | Uint8Array;
type UploadOptions = { shareWithUsers?: Array<string>, onProgress?: Function };

function upload(clearData: Data, options?: UploadOptions): Promise<FileId>
Parameters Description
clearData: Data The data of the file to upload
options: UploadOptions Object defining the upload options
Returns
Promise<string> The fileId of the uploaded file
Throws Description
InvalidArgument Some recipients have not been found, or clearData is not a valid input
PreconditionFailed FileKit session has not been started
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable

UploadOptions

The shareWithUsers option allows you to specify who will be able to decrypt a file. If none is provided, only the user who uploaded the file will be able to decrypt it.

Fields Default Description
shareWithUsers: Array<string> [] The user public identities to share with (the current user's identity will be automatically appended)
onProgress: Function (none) A handler function to track progress. It will be called several times with a single argument in the following format:
{ currentBytes: number, totalBytes: number }

Download

Download and decrypt a file.

type DownloadOptions = { onProgress?: Function };

function download(fileId: FileId, options?: DownloadOptions): Promise<File>
Parameters Description
fileId: string The fileId of the file to download
options: DownloadOptions Object defining the download options
Returns
Promise<File> The decrypted data in the File format
Throws Description
InvalidArgument The fileId provided does not match with any file uploaded on FileKit
PreconditionFailed FileKit session has not been started
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable

DownloadToDisk

Download, decrypt and save a file to disk.

function downloadToDisk(fileId: FileId, options?: DownloadOptions): Promise<void>
Parameters Description
fileId: string The fileId of the file to download
options: DownloadOptions Object defining the download options
Returns
Promise The promise is fulfilled once the download operation is done
Throws Description
InvalidArgument The fileId provided does not match with any file uploaded on FileKit
PreconditionFailed FileKit session has not been started
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable

DownloadOptions

Fields Default Description
onProgress: Function (none) A handler function to track progress. It will be called several times with a single argument in the following format:
{ currentBytes: number, totalBytes: number }

Share

Note

This documentation uses flow type annotations.

Share

Share one or several uploaded files with additional recipients.

function share(fileIds: Array<FileId>, options: SharingOptions): Promise<void>
Parameters
fileIds: Array<FileId> The IDs of the files to share
options: SharingOptions An object defining the recipients of the sharing operation
Returns
Promise The promise is fulfilled once the operation is done
Throws Description
InvalidArgument Some recipients, or some file IDs have not been found
PreconditionFailed FileKit session has not been started
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable

SharingOptions

The shareWithUsers option allows you to specify who will be able to decrypt a file. If none is provided, only the user who uploaded the file will be able to decrypt it.

Fields Default Description
shareWithUsers: Array<string> [] The user public identities to share with (the current user's identity will be automatically appended)

Error handling

All errors thrown by FileKit extend the same TankerError base class and have the following fields:

Field Description
name the name of the (sub)class as a string
message additional details about the error

Here is the list of possible errors:

Error Description
InternalError Tanker internal error, thrown as a last resort
InvalidArgument Developer error, one of the function's argument is invalid
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
PreconditionFailed Developer error, a function's precondition was violated

Here is a code example demonstrating various levels of granularity in error handling:

import { errors } from '@tanker/filekit';

try {
  await fileKit.start(...);
} catch(e) {
  if (e instanceof errors.InvalidArgument) {
    /* specific FileKit error handling */
  } else if (e instanceof errors.TankerError) {
    /* generic Tanker error handling */
  } else {
    /* generic non-Tanker error handling */
  }
}