Browser Upload SDK

The Browser Upload SDK is equipped with multi-chain storage capabilities powered by Spheron.

Installation

Using NPM

npm i @spheron/browser-upload

Using Yarn

yarn add @spheron/browser-upload

Usage

The Browser SDK allows you to upload files directly from your browser to IPFS, Filecoin, or Arweave.
To use the Browser SDK, you have to set up the following:

1. A web server will be used by the frontend to get the uploadToken for uploading the data.
2. A web app that uses @spheron/browser-upload to upload files directly from the browser.

You can checkout the working example here (opens in a new tab).

Server

You have to set up a web server with an endpoint that will be used by the frontend to fetch the token for upload. In the example, we have created a /initiate-upload endpoint. Make use of the createSingleUploadToken method from @spheron/storage package to generate the uploadToken.

import { SpheronClient, ProtocolEnum } from "@spheron/storage";
 
...
 
app.get("/initiate-upload", async (req, res, next) => {
  try {
    const bucketName = "example-browser-upload"; // use your preferred name
    const protocol = ProtocolEnum.IPFS; // use your preferred protocol
    const token = process.env.SPHERON_TOKEN; // add your access token in .env or paste it here
 
    const client = new SpheronClient({ token });
 
    const { uploadToken } = await client.createSingleUploadToken({
      name: bucketName,
      protocol,
    });
 
    res.status(200).json({
      uploadToken,
    });
  } catch (error) {
    console.error(error);
    next(error);
  }
});

You need to Create an Access Token to create the client.

Function createSingleUploadToken takes two parameters:

• name - (string) - Represents the name of the bucket on which you are uploading the data.
• protocol - (string) - The protocol on which the data will be uploaded. The supported protocols are [ ARWEAVE, IPFS, FILECOIN].

Response

interface TokenRes {
  uploadToken: string;
}

Client

The browser-upload provides three methods:

Upload

You have to send a request to your server to create the uploadToken that will be used to upload files from the browser. In the example, we are sending a request to the /initiate-upload endpoint. Make use of the upload method from @spheron/browser-upload to upload your files.

import { upload } from "@spheron/browser-upload";
 
...
 
const response = await fetch(`<BACKEND_URL>/initiate-upload`); // get the temporary access token from the server
const resJson = await response.json();
const token =  resJson.uploadToken;
 
let currentlyUploaded = 0;
 
const { uploadId, bucketId, protocolLink, dynamicLinks } = await upload(files, {
  token,
  onChunkUploaded: (uploadedSize, totalSize) => {
    currentlyUploaded += uploadedSize;
    console.log(`Uploaded ${currentlyUploaded} of ${totalSize} Bytes.`);
  },
});
 
...

This flow allows you to control who can use your uploadToken to upload files.
Function upload takes two parameters:

• files - ( File[] | FileList ) - An array of files to be uploaded.
• configuration: An object with the following parameters:
  1. configuration.token
     • The upload token was fetched from the server.
  2. configuration.onChunkUploaded (Optional)
     • callback function (uploadedSize: number, totalSize: number) => void. The function will be called multiple times, depending on the upload size. The function will be called each time a chunk is uploaded, with two parameters. The first one uploadedSize represents the size in Bytes for the uploaded chunk. The totalSize represents the total size of the upload in Bytes.

Response

interface UploadRes {
  uploadId: string;
  bucketId: string;
  protocolLink: string;
  dynamicLinks: string[];
  cid: string;
}

Encrypt Upload

Used to encrypt a string or a file and upload it to IPFS.

const { uploadId, bucketId, protocolLink, dynamicLinks } =
  await spheron.encryptUpload({
    authSig,
    accessControlConditions,
    chain,
    filePath,
    litNodeClient: client,
    configuration: {
      token,
    },
  });

Parameters of encryptUpload:

• authSig - (optional) The authSig of the user. You can use checkAndSignAuthMessage function from @lit-protocol/lit-node-client (opens in a new tab) to create it. Checkout the example (opens in a new tab).

• sessionSigs: - (optional) the session signatures to use to authorize the user with the nodes.

• accessControlConditions - (optional) The access control conditions that the user must meet to obtain this signed token. This could be possession of an NFT, for example.

• evmContractConditions - (optional) EVM Smart Contract access control conditions that the user must meet to obtain this signed token. This could be possession of an NFT, for example. This is different than accessControlConditions because accessControlConditions only supports a limited number of contract calls. evmContractConditions supports any contract call.

• solRpcConditions - (optional) Solana RPC call conditions that the user must meet to obtain this signed token. This could be possession of an NFT, for example.

• unifiedAccessControlConditions - (optional) An array of unified access control conditions. You may use AccessControlCondition, EVMContractCondition, or SolRpcCondition objects in this array, but make sure you add a conditionType for each one.

  NOTE: The function requires either accessControlConditions, evmContractConditions, solRpcConditions or unifiedAccessControlConditions.

• chain - The chain name of the chain that this contract is deployed on.

• string - (optional) The string you wish to encrypt.

• file - (optional) The File you wish to encrypt.

  NOTE: The function requires either string of file parameters to be passed.

• litNodeClient - An instance of LitNodeClient that is already connected.

• configuration:

  • token - The upload token was fetched from the server.
  • onChunkUploaded - (optional) callback function (uploadedSize: number, totalSize: number) => void. The function will be called multiple times, depending on the upload size. The function will be called each time a chunk is uploaded, with two parameters. The first one uploadedSize represents the size in Bytes for the uploaded chunk. The totalSize represents the total size of the upload in Bytes.

Response

interface UploadRes {
  uploadId: string;
  bucketId: string;
  protocolLink: string;
  dynamicLinks: Domain[];
  cid: string;
}

Decrypt Upload

Used to decrypt the data of the previously encrypted upload.

const decryptedData: Uint8Array = spheron.decryptUpload({
  authSig,
  ipfsCid,
  litNodeClient,
});

Function decryptUpload parameters:

• authSig - (optional) The authSig of the user. You can use checkAndSignAuthMessage function from @lit-protocol/lit-node-client (opens in a new tab) to create it Checkout the example (opens in a new tab).
• sessionSigs - (optional) the session signatures to use to authorize the user with the nodes.
• ipfsCid - The IPFS cid of the upload that was previously encrypted & uploaded.
• litNodeClient - An instance of LitNodeClient that is already connected.

Response

• The function returns an Uint8Array, which represents the decrypted data.
  NOTE: Checkout the example (opens in a new tab) on how to use decryptUpload function.