Fleek Storage JS

Fleek provides everything you need to securely store files on IPFS and distribute them for the web applications.

Fleek Storage JS is an SDK that will allow you to easily interact programatically with Fleek Storage. It allows getting file content, hash, publicUrl, and uploading files.

Getting the API key¶

From the Fleek CLI¶

The Fleek CLI is a tool that allows access to Fleek's products from the command line.

Installation¶

npm install -g @fleekhq/fleek-cli

Run the following command:

fleek login

It should open a browser window prompting you to log in. If you are already logged in, it will automatically close the browser window and generate the keys.

Next, run the command

fleek  whoami

Take note of the fields apiKey and apiSecret which will be needed in the next step.

From the Web app¶

You can also generate a new api key from the Web app at app.fleek.co.

The api generator is located in the user settings.

The new keys can be generated in the api section by clicking on Create API keys. Make sense to copy the secret somewhere because it is only visible once.

Installing NPM Package¶

The package can be installed through npm.

npm install @fleekhq/fleek-storage-js

It can also be installed through yarn.

yarn add @fleekhq/fleek-storage-js

Importing¶

The SDK can be imported using an import statement.

import fleekStorage from '@fleekhq/fleek-storage-js'

The SDK can also be imported using a require.

const fleekStorage = require('@fleekhq/fleek-storage-js')

Methods¶

get¶

The get method is for fetching individual files, either the content or related data, such as the key, hash and publicUrl.

Example of usage:

const myFile = await fleekStorage.get({
  apiKey: 'my-key',
  apiSecret: 'my-secret',
  key: 'my-file-key',
  getOptions: [
    'data',
    'bucket',
    'key',
    'hash',
    'publicUrl'
  ],
})

Input parameters of get:

param	type	description
apiKey	String	The api key used for authentication
apiSecret	String	The api secret used for authentication
key	String	The key identifying the requested file in the bucket
bucket	String, optional, defaults to the default account bucket	The name of the bucket containing the file. A bucket is created by default with every Fleek account
getOptions	Array, optional, defaults to ['data']	An array specifying what type of information to retrieve concerning the file. Possible values for the array includes `data`, `bucket`, `hash`, `key`, `publicUrl`

upload¶

The upload method uploads a file, identified by a key, to a bucket. The function returns the hash of the file, the publicUrl, the key and the bucket.

Example of usage:

fs.readFile(filePath, async (error, fileData) => {
  const uploadedFile = await fleekStorage.upload({
    apiKey: 'my-key',
    apiSecret: 'my-secret',
    key: 'my-file-key',
    ContentType: 'image/png'
    data: fileData,
    httpUploadProgressCallback: (event) => {
      console.log(Math.round(event.loaded/event.total*100)+ '% done');
    }
  });
})

It is advised that your client code now handle errors for the upload file call. Previously, the library was swallowing errors in an attempt to handle errors during conversion from v0 hash to v1 hash. Now the client is handling that error separately and rejecting the promise for other errors. If your client code isn't handling errors on this call your app can break. You can see the community improvement PR proposal here for further context.

Input parameters of upload

param	type	description
apiKey	String	The api key used for authentication
apiSecret	String	The api secret used for authentication
key	String	The key identifying the requested file in the bucket
bucket	String, optional, defaults to the default account bucket	The name of the bucket containing the file. A bucket is created by default with every Fleek account
data	Any	The data of the file to be uploaded
httpUploadProgressCallback	Function	Callback function to track the progress of the upload
ContentType	String	Type of data to be uploaded, MIME type

streamUpload¶

The streamUpload method uploads a file, identified by a key, to a bucket. The function returns the hash of the file, the publicUrl, the key and the bucket. The difference between upload and streamUpload is that streamUpload does not store the entire file in memory prior to uploading, which is useful for very large files.

Example of usage:

  const stream  = fs.createReadStream('./bike.mp4');

  const uploadedFile = await fleekStorage.streamUpload({
    apiKey: 'my-key',
    apiSecret: 'my-secret',
    key: 'my-file-key',
    stream,
  });

Input parameters of streamUpload

param	type	description
apiKey	String	The api key used for authentication
apiSecret	String	The api secret used for authentication
key	String	The key identifying the requested file in the bucket
bucket	String, optional, defaults to the default account bucket	The name of the bucket containing the file. A bucket is created by default with every Fleek account
stream	Any	The data of the file to be uploaded as a stream

deleteFile¶

The deleteFile method deletes a file, identified by its key and bucket. The function returns the key and bucket of the deleted file if successful. If the file does not exist, the method will still execute successfully.

Example of usage:

  await fleekStorage.deleteFile({
    apiKey: 'my-key',
    apiSecret: 'my-secret',
    key: 'my-file-key',
    bucket: 'my-bucket',
  });

Input parameters of deleteFile

param	type	description
apiKey	String	The api key used for authentication
apiSecret	String	The api secret used for authentication
key	String	The key identifying the file in the bucket
bucket	String, optional, defaults to the default account bucket	The name of the bucket containing the file. A bucket is created by default with every Fleek account

listFiles¶

The listFiles method is for fetching information about all files in a bucket such as the key, hash and publicUrl.

Example of usage:

const files = await fleekStorage.listFiles({
  apiKey: 'my-key',
  apiSecret: 'my-secret',
  getOptions: [
    'bucket',
    'key',
    'hash',
    'publicUrl'
  ],
})

Input parameters of listFiles

param	type	description
apiKey	String	The api key used for authentication
apiSecret	String	The api secret used for authentication
bucket	String, optional, defaults to the default account bucket	The name of the bucket containing the file. A bucket is created by default with every Fleek account
getOptions	Array, optional, defaults to ['key', 'bucket', 'publicUrl']	An array specifying what type of information to retrieve concerning the file. Possible values for the array includes `bucket`, `hash`, `key`, `publicUrl`

listBuckets¶

The listBuckets method returns an array of bucket names associated with the api key's account.

Example of usage:

const buckets = await fleekStorage.listBuckets({
  apiKey: 'my-key',
  apiSecret: 'my-secret',
})

Input parameters of listBuckets

param	type	description
apiKey	String	The api key used for authentication
apiSecret	String	The api secret used for authentication

getFileFromHash¶

getFileFromHash is a utility function that downloads a file's data from Fleek's IPFS gateway using the hash. The key and secret is not required since the gateway is publicly available.

The option getFileFromHashOptions: ['buffer'] will return the file as a buffer which can more readily be uploaded to Fleek storage with the upload method.

Example of usage:

const myFile = await fleekStorage.getFileFromHash({
  hash: 'bafybeige4bhzjvrptn7fdz7mqgigzoczcliqpuo7km4jm7vgjg2pbmuhna',
})

Input parameters of getFileFromHash

param	type	description
hash	String	The hash of the requested file
getFileFromHashOptions	Array, Optional, defaults to []	Options provided to the method. Possible values: `buffer`, which will return a buffer.