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
getSignText(address: string):string
The getSignText
method is used to obtain plaintext for wallet signatures.
Parameters
address: string
Required parameter: the wallet address to be signed.
Returns
signText: string
The plaintext information for the signature.
Examples
let address = '' // metamask address
const signMessage = await authclient.getSignText(address)
verifySign(address: string, signature: string):ValidSignResult
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: string
Required parameter: the address to be validated for the signature.
signature: string
Required 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 uploadfolderPath: string
: The folder path within the temporary Bucket used for file uploadtoken: string
: Token for invoking 4EVER PinaccessKeyId: string
: The KeyID for the temporary S3 BucketsecretAccessKey: string
: The secret key for the temporary S3 BucketsessionToken: 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:BucketClientParams
The required properties for this object include:
accessKeyId:string
: Access key ID for the BucketsecretAccessKey: string
: Private key for the BucketsessionToken:string
: Temporary token, valid for 24 hoursendpoint: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
upload(params: ClientUploadParams) :UploadResult
The upload
method is used for uploading files to the specified Bucket.
Parameters
params: ClientUploadParams
Required 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 streamContentType?: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:PinningClientParams
The 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
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
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: strings
Required 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
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
replacePin(requestid: string, addPin: AddPinParams):PinInfo
Parameters
requestid: strings
Required 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)
Last updated