Browser Upload SDK
The Browser Upload SDK is equipped with multi-chain storage capabilities powered by Spheron.
The package is only meant for Browser environments.
NOTE: You need to generate an uploadToken
for uploading data with
Browser Upload SDK. You can do that by creating a server.
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:
- A web server will be used by the frontend to get the
uploadToken
for uploading the data. - 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
If you are using the >=2.0.0
version of the @spheron/browser-upload
package, you also need to use the >=2.0.0
version of the @spheron/storage
on the server
side.
If you are using the <2.0.0
version of the @spheron/browser-upload
package, you also need to use the <2.0.0
version of the @spheron/storage
on the server
side.
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
.
NOTE: The uploadToken
can only be used for a single upload and has an
expiration of 10 minutes.
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.
- For
>=2.0.0
versions, Please choosestorage
type in the dashboard while generating the Access Token. - For
<2.0.0
versions, Please choosestatic site
type in the dashboard while generating the Access Token.
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.
NOTE: The uploadToken
can only be used for a single upload and has an
expiration of 10 minutes.
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:
configuration.token
- The upload token was fetched from the server.
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 oneuploadedSize
represents the size in Bytes for the uploaded chunk. ThetotalSize
represents the total size of the upload in Bytes.
- callback function
Response
interface UploadRes {
uploadId: string;
bucketId: string;
protocolLink: string;
dynamicLinks: string[];
cid: string;
}
NOTE: The CID property will only have value for IPFS and Filecoin uploads.
Encrypt Upload
Used to encrypt a string or a file and upload it to IPFS.
NOTE: Both the encryptUpload
functions require an instance of
LitNodeClient that is already connected. To create an instance, checkout the
@lit-protocol/lit-node-client (opens in a new tab)
package or our
example (opens in a new tab)
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
, orSolRpcCondition
objects in this array, but make sure you add a conditionType for each one.NOTE: The function requires either
accessControlConditions
,evmContractConditions
,solRpcConditions
orunifiedAccessControlConditions
. -
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
offile
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 oneuploadedSize
represents the size in Bytes for the uploaded chunk. ThetotalSize
represents the total size of the upload in Bytes.
Response
interface UploadRes {
uploadId: string;
bucketId: string;
protocolLink: string;
dynamicLinks: Domain[];
cid: string;
}
NOTE: Checkout the
example (opens in a new tab)
on how to use encryptUpload
function.
Decrypt Upload
Used to decrypt the data of the previously encrypted upload.
NOTE: Both the decryptUpload
functions require an instance of
LitNodeClient that is already connected. To create an instance, checkout the
@lit-protocol/lit-node-client (opens in a new tab)
package or our
example (opens in a new tab)
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.