# 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](https://github.com/yepCing/4everland-sdk/tree/main) for guidance.

## Get started

Install @4everland/upload-pin

```JavaScript
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: 

<pre><code><strong>https://auth.api.4everland.org
</strong></code></pre>

**Examples**

```JavaScript
// 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: string`**&#x52;equired parameter: the wallet address to be signed.<br>

**Returns**

**`signText: string`**&#x54;he plaintext information for the signature.

**Examples**

```JavaScript
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: string`**&#x52;equired parameter: the address to be validated for the signature.\
\&#xNAN;**`signature: string`**&#x52;equired parameter: the signature to be verified.<br>

**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**

```JavaScript
// 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`**&#x54;he 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**

```JavaScript
//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: ClientUploadParams`**&#x52;equired 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.

  &#x20;  \- Uploaded portion: e.loaded   \
  &#x20;  \- Total: e.total

**Examples**

```JavaScript
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`**&#x54;he 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**

```JavaScript
//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](https://ipfs.github.io/pinning-services-api-spec/#operation/addPin) under the "Add pin object" section.

**Parameters**

**`addPin: AddPinParams`**

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

**Returns**

**`PinInfo`**

```JavaScript
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**

```JavaScript
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](https://ipfs.github.io/pinning-services-api-spec/#operation/getPinByRequestId) under the "Get pin object" section.

**Parameters**

**`requestid: strings`**&#x52;equired parameter: the `requestid` from the response of the `addPin` method.

**Returns**

**`PinInfo`**

```JavaScript
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**

```JavaScript
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](https://ipfs.github.io/pinning-services-api-spec/#operation/getPins) under the "List pin object" section.<br>

**Parameters**

**`params: PinParams`**

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

**Returns**

**`PinInfo`**

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

**Examples**

```JavaScript
await pinclinet.listPin()
```

### **`replacePin(requestid: string, addPin: AddPinParams):PinInfo`**

**Parameters**

**`requestid: strings`**&#x52;equired parameter: the `requestid` from the response of the `addPin` method.**`addPin: AddPinParams`**

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

**Returns**

**`PinInfo`**

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

**Examples**

```JavaScript
await pinclinet.replacePin(requestid,addpinparams)
```

<br>