Storage SDK

Introduction

The 4EVER Pin SDK provides a set of tools for directly uploading files to a specified 4EVER Pin account list. It includes three classes: AuthClient, BucketClient, and PinClient. Developers can refer to this documentation to combine and utilize these three classes to achieve file uploading functionality to 4EVER Pin. They can also refer to the 4EVER Pin SDK Demo for guidance.

Get started

Install @4everland/upload-pin

npm i @4everland/upload-pin
yarn add @4everland/upload-pin

AuthClient

To obtain the relevant permission information for the file upload functionality, developers would need to utilize the methods within the AuthClient class, which include getSignText and verifySign. These methods are essential for acquiring the necessary permissions and verifying the authentication of the file upload process.

Parameters

url: string Required parameter

The available Auth API to be filled in is:

https://auth.api.4everland.org

Examples

// New AuthClint instance
import { AuthClient } from '@4everland/upload-pin'

const url = '' 
const authclient = new AuthClient(url)

getSignText(address: string):string

The getSignText method is used to obtain plaintext for wallet signatures.

Parameters

address: stringRequired parameter: the wallet address to be signed.

Returns

signText: stringThe plaintext information for the signature.

Examples

let address = '' // metamask address
const signMessage = await authclient.getSignText(address)

verifySign(address: string, signature: string):ValidSignResult

The verifySign method is used to verify the validity of the signature. Upon successful verification, the relevant permission information required for file upload can be obtained.

Parameters

address: stringRequired parameter: the address to be validated for the signature. signature: stringRequired parameter: the signature to be verified.

Returns

verifySign returns a ValidSignResult object with seven properties:

• expiration: number: The expiration time of the signature (2 hours)

• accessBucket: string: The temporary Bucket used for file upload

• folderPath: string: The folder path within the temporary Bucket used for file upload

• token: string: Token for invoking 4EVER Pin

• accessKeyId: string: The KeyID for the temporary S3 Bucket

• secretAccessKey: string: The secret key for the temporary S3 Bucket

• sessionToken: string: The STS Token for the temporary S3 Bucket

Examples

// Verification signature
// if expiration expired, you need Verification signature again
const { expiration } = await client.verifySign(address, signature)

BucketClient

The BucketClient class contains an upload method used for uploading files to a specified Bucket and obtaining the file CID.

Parameters

params:BucketClientParamsThe required properties for this object include:

• accessKeyId:string: Access key ID for the Bucket

• secretAccessKey: string: Private key for the Bucket

• sessionToken:string: Temporary token, valid for 24 hours

• endpoint:string: S3 endpoint, currently available at 'https://endpoint.4everland.co'

Examples

//New BucketClint instance
import { BucketClient } from '@4everland/upload-pin'

const {params}= {
  accessKeyId: ''
  secretAccessKey: ''
  sessionToken: ''
  endpoint: 'https://endpoint.4everland.co'
}
const bucketclient = new BucketClient(params)

upload(params: ClientUploadParams) ：UploadResult

The upload method is used for uploading files to the specified Bucket.

Parameters

params: ClientUploadParamsRequired parameters for this object include the following properties:

• Key: string: File path (folderPath + '/' + file name, where folderPath is a parameter returned from verifySign)

• Body: StreamingBlobPayloadInputType: File stream

• ContentType?:string: File type

Returns

The upload method returns an UploadResult object with three properties:

• abort: () => Promise<void>: Calling this function can terminate the file upload process.

• done: () => Promise<{ cid: string }>: Calling this function after the file upload is complete will provide its CID (object).

• progress: (cb?: (e: Progress) => void) => void: This callback function logs the file upload process steps in the console.

  - Uploaded portion: e.loaded - Total: e.total

Examples

const task = bucketclient.upload({
    Key: folderPath + '/'+ file.name,
    Body: file,
    ContentType: file.type
})

task.progress((e) => {
    console.log(e.loaded)
    console.log(e.total)
})

const { cid } = await task.done()

PinClient

Based on the Pinning Service API, the PinClient class includes three methods: addPin, getPin, and listPin. These methods enable the uploading of CIDs to 4EVER Pin and querying for relevant information.

Parameters

params:PinningClientParamsThe required properties for this object include the following:

• baseURL:string: Pinning service endpoint. Currently available at 'https://api.4everland.dev'

• accessToken: string: Access token for 4EVER Pin

Examples

//New BucketClint instance
import { PintClient } from '@4everland/upload-pin'

const {params}= {
  baseURL: 'https://api.4everland.dev'
  accessToken:''
}
const pinclient = new PinClient(params)

addPin(addPin: AddPinParams):PinInfo

The addPin method is used to directly add a CID to 4EVER Pin. This method is part of the Pinning Service API, and the meaning of the request and response parameters can be found in the Pinning Service API documentation under the "Add pin object" section.

Parameters

addPin: AddPinParams

export interface AddPinParams {
  cid: string
  name?: string
  origins?: string[]
  meta?: {
    [K in string]: string
  }

Returns

PinInfo

export interface PinInfo {
  requestid: string
  status: string
  created: string
  pin: {
    cid: string
    name?: string
    origins?: string[]
    meta?: {
      [K in string]: string
    }
  }
  delegates: string[]
  info?: {
    [K in string]: string
  }
}

Examples

const { requestid } = await pinclinet.addPin({
  cid
})

getPin(requestid: string):PinInfo

The getPin method is utilized to query the specified pinned file's information and status. This method is part of the Pinning Service API, hence, the meanings of its request and response parameters can be referenced in the Pinning Service API documentation under the "Get pin object" section.

Parameters

requestid: stringsRequired parameter: the requestid from the response of the addPin method.

Returns

PinInfo

export interface PinInfo {
  requestid: string
  status: string
  created: string
  pin: {
    cid: string
    name?: string
    origins?: string[]
    meta?: {
      [K in string]: string
    }
  }
  delegates: string[]
  info?: {
    [K in string]: string
  }
}

Examples

await pinclinet.getPin(requestid)

listPin(params: PinParams):ListPin

The listPin method is used to query the specified pinned file's information and status. This method is part of the Pinning Service API, and its request and response parameters can be referenced in the Pinning Service API documentation under the "List pin object" section.

Parameters

params: PinParams

export interface PinParams {
  cid?: string
  name?: string
  status?: string
  limit?: number
  before?: string
  after?: string
}

Returns

PinInfo

export interface ListPin {
  count: number
  results: PinInfo[]
}

Examples

await pinclinet.listPin()

replacePin(requestid: string, addPin: AddPinParams):PinInfo

Parameters

requestid: stringsRequired parameter: the requestid from the response of the addPin method.addPin: AddPinParams

export interface AddPinParams {
  cid: string
  name?: string
  origins?: string[]
  meta?: {
    [K in string]: string
  }

Returns

PinInfo

export interface ListPin {
  count: number
  results: PinInfo[]
}

Examples

await pinclinet.replacePin(requestid,addpinparams)