Storage SDK

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

⚠️

The package is only meant for Node.js environments and will not work in a browser or frontend apps.

Installation

Using NPM

npm i @spheron/storage

Using Yarn

yarn add @spheron/storage

Usage

To use the Spheron Storage SDK, you have to create an instance of SpheronClient.

import { SpheronClient, ProtocolEnum } from "@spheron/storage";
 
const client = new SpheronClient({ token });

The SpheronClient constructor takes an object that has one property token. Follow the instructions in the DOCS (opens in a new tab) to generate this token.

NOTE: When you are creating the tokens, please choose web app type in the dashboard.

Available Methods

The SpheronClient instance provides several methods for working with buckets. Here's the list of all the supported methods.

Upload

Used to upload a file/directory to the specified protocol.

let currentlyUploaded = 0;
 
const { uploadId, bucketId, protocolLink, dynamicLinks } = await client.upload(
  filePath,
  {
    protocol: ProtocolEnum.IPFS,
    name,
    onUploadInitiated: (uploadId) => {
      console.log(`Upload with id ${uploadId} started...`);
    },
    onChunkUploaded: (uploadedSize, totalSize) => {
      currentlyUploaded += uploadedSize;
      console.log(`Uploaded ${currentlyUploaded} of ${totalSize} Bytes.`);
    },
  }
);

Function upload takes two parameters:

filePath - (string) - The path to the file/directory that will be uploaded.
configuration: An object with the following parameters:
1. configuration.name
  - Represents the name of the bucket on which you are uploading the data.
2. configuration.protocol
  - The protocol on which the data will be uploaded. The supported protocols are [ ARWEAVE, IPFS, FILECOIN].
3. configuration.onUploadInitiated (Optional)
  - Callback function (uploadId: string) => void. The function will be called once, when the upload is initiated, right before the data is uploaded. The function will be called with one parameter, uploadId, which represents the id of the started upload.
4. 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: Domain[];
}

Get Bucket

Used to get the bucket information for the specified bucketId.

const bucket: Bucket = await client.getBucket(bucketId);

Function getBucket takes just one parameter:

bucketId - (string) - The id of the bucket.

Response

enum  BucketStateEnum {
  MAINTAINED = "MAINTAINED",
  ARCHIVED = "ARCHIVED",
}
 
interface Bucket {
  id: string;
  name: string;
  organizationId: string;
  state: BucketStateEnum;
  domains: Domain[];
}

Get Bucket Domains

Used to get the domains that are attached to the specified bucketId.

const bucketDomains: Domain[] = await client.getBucketDomains(bucketId);

Function getBucketDomains takes just one parameter:

bucketId - (string) - The id of the bucket.

Response

enum DomainTypeEnum {
  DOMAIN = "domain",
  SUBDOMAIN = "subdomain",
  HANDSHAKE_DOMAIN = "handshake-domain",
  HANDSHAKE_SUBDOMAIN = "handshake-subdomain",
  ENS_DOMAIN = "ens-domain",
}
 
interface Domain {
  id: string;
  name: string;
  link: string;
  verified: boolean;
  bucketId: string;
  type: DomainTypeEnum;
}

Get Bucket Domain

Used to get the information about the specific domain.

const bucketDomain: Domain = await client.getBucketDomain(
  bucketId,
  domainIdentifier
);

Function getBucketDomain takes two parameters:

bucketId - (string) - The id of the bucket.
domainIdentifier - (string) - It can ether be the id of the domain, or the name of the domain.

Response

enum DomainTypeEnum {
  DOMAIN = "domain",
  SUBDOMAIN = "subdomain",
  HANDSHAKE_DOMAIN = "handshake-domain",
  HANDSHAKE_SUBDOMAIN = "handshake-subdomain",
  ENS_DOMAIN = "ens-domain",
}
 
interface Domain {
  id: string;
  name: string;
  link: string;
  verified: boolean;
  bucketId: string;
  type: DomainTypeEnum;
}

Add Bucket Domain

Used to add a new domain to the specified bucket. The link property needs to have the protocolLink value of an existing bucket id. After adding a new domain, you will need to setup the record on your DNS provider:

domain: you should create a A type record with value 13.248.203.0, and the same name as the domain you have added.
subdomain : you should create a CNAME type record with value cname.spheron.io, and the same name as the domain you have added.
handshake-domain: you should create a A type record with value ipfs.namebase.io, and @ for name. Also you should create a TXT type record with link for a value, and _contenthash for name.
handshake-subdomain: you should create a A type record with value ipfs.namebase.io, and the same name as the domain you have added. Also you should create a TXT type record with link for a value, and _contenthash.<name_of_the_domain> for name.
ens-domain: you should create a CONTENT type record with link for a value, and the same name as the domain you have added.

const bucketDomain: Domain = await client.addBucketDomain(bucketId, {
  link,
  type,
  name,
});

Function addBucketDomain takes two parameters:

bucketId - (string) - The id of the bucket.
bucketDetails - An object with the link, type and name of the bucket to be added.

After you have setup the record on your DNS provider, then you should call the verifyBucketDomain method to verify your domain on Spheron. After the domain is verified, the data behind the link will be cached on the Spheron CDN.

Response

enum DomainTypeEnum {
  DOMAIN = "domain",
  SUBDOMAIN = "subdomain",
  HANDSHAKE_DOMAIN = "handshake-domain",
  HANDSHAKE_SUBDOMAIN = "handshake-subdomain",
  ENS_DOMAIN = "ens-domain",
}
 
interface Domain {
  id: string;
  name: string;
  link: string;
  verified: boolean;
  bucketId: string;
  type: DomainTypeEnum;
}

Update Bucket Domain

Used to update an existing domain of the Bucket.

const bucketDomain: Domain = await client.updateBucketDomain(
  bucketId,
  domainIdentifier,
  {
    link,
    name,
  }
);

Function updateBucketDomain takes three parameters:

bucketId - (string) - The id of the bucket.
domainIdentifier - (string) - It can ether be the id of the domain, or the name of the domain.
options - An object with the link and name of the bucket to be updated.

Response

enum DomainTypeEnum {
  DOMAIN = "domain",
  SUBDOMAIN = "subdomain",
  HANDSHAKE_DOMAIN = "handshake-domain",
  HANDSHAKE_SUBDOMAIN = "handshake-subdomain",
  ENS_DOMAIN = "ens-domain",
}
 
interface Domain {
  id: string;
  name: string;
  link: string;
  verified: boolean;
  bucketId: string;
  type: DomainTypeEnum;
}

Verify Bucket Domain

Used to verify the domain, after which the content behind the domain will be cached on CDN.

const domainStatus: Domain = await client.verifyBucketDomain(
  bucketId,
  domainIdentifier
);

Function verifyBucketDomain takes two parameters:

bucketId - (string) - The id of the bucket.
domainIdentifier - (string) - It can ether be the id of the domain, or the name of the domain.

Response

enum DomainTypeEnum {
  DOMAIN = "domain",
  SUBDOMAIN = "subdomain",
  HANDSHAKE_DOMAIN = "handshake-domain",
  HANDSHAKE_SUBDOMAIN = "handshake-subdomain",
  ENS_DOMAIN = "ens-domain",
}
 
interface Domain {
  id: string;
  name: string;
  link: string;
  verified: boolean;
  bucketId: string;
  type: DomainTypeEnum;
}

Delete Bucket Domain

Used to delete the domain of the Bucket.

await client.deleteBucketDomain(bucketId, domainIdentifier);

Function deleteBucketDomain takes two parameters:

bucketId - (string) - The id of the bucket.
domainIdentifier - (string) - It can ether be the id of the domain, or the name of the domain.

Archive Bucket

Used to archive the Bucket. New uploads cannot be created for an archived bucket.

await client.archiveBucket(bucketId);

Function archiveBucket takes just one parameter:

bucketId - (string) - The id of the bucket.

Unarchive Bucket

Used to unarchive the Bucket.

await client.unarchiveBucket(bucketId);

Function unarchiveBucket takes just one parameter:

bucketId - (string) - The id of the bucket.

Get Bucket Upload Count

Used to get the number of uploads for the specified bucket.

const { total, successful, failed, pending } =
  await client.getBucketUploadCount(bucketId);

Function getBucketUploadCount takes just one parameter:

bucketId - (string) - The id of the bucket.

Response

interface BucketRes {
  total: number;
  successful: number;
  failed: number;
  pending: number;
}

Get Bucket Uploads

Used to get the uploads of the bucket. The default value for skip is 0. The default value for limit is 6.

const bucketUploads: Upload[] = await client.getBucketUploads(bucketId, { skip: number; limit: number; });

Function getBucketUploads takes two parameters:

bucketId - (string) - The id of the bucket.
options - An object with the skip and limit of the bucket to be updated.

Response

enum UploadStatusEnum {
  PENDING = "Pending",
  CANCELED = "Canceled",
  DEPLOYED = "Deployed",
  FAILED = "Failed",
  TIMED_OUT = "TimedOut",
}
 
interface Upload {
  id: string;
  protocolLink: string;
  buildDirectory: string[];
  status: UploadStatusEnum;
  memoryUsed: number;
  bucketId: string;
  protocol: string;
}

Get Upload

Used to get the upload by its id.

const upload: Upload = await client.getUpload(uploadId);

Function getUpload takes just one parameter:

uploadId - (string) - The upload id of the file uploaded using Spheron SDK.

Response

interface Upload {
  id: string;
  protocolLink: string;
  buildDirectory: string[];
  status: UploadStatusEnum;
  memoryUsed: number;
  bucketId: string;
  protocol: string;
}

Get Organization Usage

Used to get the usage of the current active subscription of the organization.

const organization: UsageWithLimits = await client.getOrganizationUsage(
  organizationId
);

Function getOrganizationUsage takes just one parameter:

organizationId - (string) - The id of the organization.

Response

interface UsageWithLimits {
  used: {
    bandwidth: number, // the bytes of bandwidth used for the current subscription
    storageArweave: number, // the bytes of used Arweave storage for the current subscription
    storageIPFS: number, // the bytes of used IPFS storage for the current subscription
    domains: number, // the number of domains and subdomain an organization has
    numberOfRequests: number, // the number of requests the organization has had till now
    parallelUploads: number, // the number of uploads are in progress for an organization
  };
  limit: {
    bandwidth: number, // the bandwidth limit for the current subscription
    storageArweave: number, // the limit in bytes for the Arweave storage for the current subscription
    storageIPFS: number, // the limit in bytes for the IPFS storage for the current subscription
    domains: number, // the limit on how many domains and subdomains can an organization have
    parallelUploads: number, // the number on how many parallel uploads an organization can have
  };
}

Get Token Scope

Used to get the scope of the token.

const tokenScope: TokenScope = await client.getTokenScope();

Function getTokenScope takes no parameters.

Response

interface TokenScope {
  user: {
    id: string,
    username: string,
    name: string,
    email: string,
  };
  organizations: {
    id: string,
    name: string,
    username: string,
  }[];
}

Publish IPNS

Used to publish IPFS Upload to IPNS.

const IPNSDetails: IPNSName = await client.publishIPNS(uploadId);

Function publishIPNS takes just one parameter:

uploadId - (string) - The upload id of the file uploaded using Spheron SDK.

Response

interface IPNSName {
  id: string;
  publishedUploadId: string;
  organizationId: string;
  createdAt: string;
  updatedAt: string;
  ipnsHash: string;
  ipnsLink: string;
}

Update IPNS Name

Used to update IPNS name to new upload id.

const IPNSDetails: IPNSName = await client.updateIPNSName(ipnsNameId, uploadId);

Function updateIPNSName takes two parameters:

ipnsNameId - (string) - The IPNS name id of a previously published upload.
uploadId - (string) - The new upload id you want IPNS Name to point to.

Response

interface IPNSName {
  id: string;
  publishedUploadId: string;
  organizationId: string;
  createdAt: string;
  updatedAt: string;
  ipnsHash: string;
  ipnsLink: string;
}

Get IPNS Name

Used to get IPNS name data by id.

const IPNSName: IPNSName = await client.getIPNSName(ipnsNameId);

Function getIPNSName takes just one parameter:

ipnsNameId - (string) - The name id of IPNS.

Response

interface IPNSName {
  id: string;
  publishedUploadId: string;
  organizationId: string;
  createdAt: string;
  updatedAt: string;
  ipnsHash: string;
  ipnsLink: string;
}

Get IPNS Names For Upload

Used to get all IPNS names for an upload id.

const IPNSNames: IPNSName[] = await client.getIPNSNamesForUpload(uploadId);

Function getIPNSNamesForUpload takes just one parameter:

uploadId - (string) - The upload id of the file uploaded using Spheron SDK.

Response

interface IPNSName {
  id: string;
  publishedUploadId: string;
  organizationId: string;
  createdAt: string;
  updatedAt: string;
  ipnsHash: string;
  ipnsLink: string;
}

Get IPNS Names For Organization

Used to get all IPNS names for an organization.

const IPNSNames: IPNSName[] = await client.getIPNSNamesForOrganization(
  organizationId
);

Function getIPNSNamesForOrganization takes just one parameter:

organizationId - (string) - Your organization id.

Response

interface IPNSName {
  id: string;
  publishedUploadId: string;
  organizationId: string;
  createdAt: string;
  updatedAt: string;
  ipnsHash: string;
  ipnsLink: string;
}

Storage Utility

Transforming CID from V0 to V1 and vice versa

The package also provides a couple of methods for transforming CID from V0 to V1 and vice verse.

import { ipfs } from "@spheron/storage";
 
const cid = <CID_VALUE>;
 
const v1 = ipfs.utils.toV1(cid);
console.log("CID V1", v1);
 
const v0 = ipfs.utils.toV0(cid);
console.log("CID V0", v0);

Spheron SDK Browser Upload SDK