From 39c647814663a1a4e3d42ff5e0de9479f40c6e4b Mon Sep 17 00:00:00 2001 From: Nico Poggi Date: Tue, 17 Aug 2021 11:51:33 -0400 Subject: [PATCH 1/4] content-for-review --- docs/storage/fleek-sdk.md | 198 ++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 3 +- 2 files changed, 200 insertions(+), 1 deletion(-) create mode 100644 docs/storage/fleek-sdk.md diff --git a/docs/storage/fleek-sdk.md b/docs/storage/fleek-sdk.md new file mode 100644 index 0000000..990f5a7 --- /dev/null +++ b/docs/storage/fleek-sdk.md @@ -0,0 +1,198 @@ +--- +date: "1" + +--- +The Fleek SDK is a tool that allows you to interact programmatically with two features on the Fleek platform **IPFS Pinning** and **Internet Computer (IC) Storage**. It is an alternative to the Fleek Storage JS (the Storage JS uses S3/MinioDB to interact with Fleek's Storage/IPFS products, while the Fleek SDK doesn't). + +--- + +## Internet Computer (IC) Storage + +First, the **IC Storage** tool. Which you can use to deploy asset canisters on the Internet Computer (through Fleek's UI), which you then interact with using this SDK tool to store and fetch files on the Internet Computer. This product and the canister deployment flow can be found in the Fleek App under the **Canisters** tab. + +## IPFS Direct Pinning + +Secondly, **IPFS Direct Pinning**. This is an alternative to using Fleek's Storage JS. When you store on Fleek's IPFS Storage via the UI, or the Storage JS, you interact with Fleek's IPFS infrastructure through an S3/MinioDB gateway that is on top of it, providing you with human readable live URLs and file metadata that are not native to IPFS. + +**Direct Pinning** is an alternative to this, and instead, using the **Fleek SDK** you can store/pin files directly to Fleek's IPFS nodes without going through that centralized layer (S3/MinioDB). + +Instead, you upload files directly using an IPFS client instance in the SDK, and only get the file's IPFS hash. It is a tradeoff approach, where you focus on an IPFS-only more decentralized option, which means your files will only be accessible through interfaces that resolve IPFS hashes (since our S3/MinioDB interface doesn't provide live Web2 URLs for resolving). + +--- + +## Using the IC Storage & Pinning SDK + +### Getting the Necessary API Key + +You can also generate a new api key from the Web app at [app.fleek.co](https://app.fleek.co). + +The api generator is located in the user settings. + +![](imgs/user-settings.png) + +The new keys can be generated in the api section by clicking on `Create API keys`. +Make sense to copy the secret somewhere because it is only visible once. + +![](imgs/api-keys.png) + +--- + +## Installation + +Use the `npm` package manager to install it. + +```bash +npm install @fleekhq/sdk +``` + +It can also be installed through yarn. + +```bash +yarn add @fleekhq/sdk +``` + +## Importing + +The SDK can be imported using an import statement. + +```ts +import { Fleek } from '@fleekhq/sdk'; +``` + +The SDK can also be imported using a require. + +```js +const { Fleek } = require('@fleekhq/sdk'); +``` +--- +## Initializing the SDK + +You can initialize an instance only with `apiKey`, but if you want to leverage IC storage you also need to provide `assetCanisterId` property. + +```ts +import { Fleek } from '@fleekhq/sdk'; + +const sdk = new Fleek({ + apiKey: 'your-api-key', // your Fleek API Key + assetCanisterId: 'your-asset-canister-id', +}); +``` +--- + +## Pinning Files to IPFS + +### ipfs() + +Returns an instance of the IPFS client. For more information check out https://www.npmjs.com/package/ipfs-http-client. + +```js +const ipfs = sdk.ipfs(); +``` + +### Uploading data + +```js +await sdk.ipfs().add(...); +``` +---- +## Storing on the Internet Computer +To start using IC Storage, you need to first **go to the Fleek app, visit the Canisters tab and deploy a new Asset Canister**. Fleek will automatically handle the deploy for you. + +This asset canister will give you the proper **Canister ID** that you will need to input, together with the API Key **(see sections above)**, in the SDK. When you use the SDK, you are storing data on this deployed canister on the Internet Computer. You can have multiple canisters, and change the ID as you interact/store in them. + +### Deploy an Asset Canister Through Fleek + +Visit the app.fleek.co app, and log in with your account. Visit the new "Canisters" tab on the menu to the left. + +**((Image))** + +Here, use the button shown to quickly deploy a new asset canister. This is a "container" canister with the sole purpose of storing/serving files. + +**((Image))** + +All good? Perfect! You can now see the canister's details, among which is the **Canister ID**, save that because you are going to need it to use the Fleek SDK. + +**((Image))** + +### Initialize the SDK for IC Storage +To begin, initialize the Fleek SDK with an API Key, and the asset canister ID you got from the previous step: + +```ts +import { Fleek } from '@fleekhq/sdk'; + +const sdk = new Fleek({ + apiKey: 'your-api-key', // your Fleek API Key + assetCanisterId: 'your-asset-canister-id', +}); +``` + +### Get Instance - assets() + +Returns an instance of the IC storage client + +```js +const assetStorage = sdk.assets(); +``` + +### Uploading Data - store() + +```js +await sdk.assets().store(key, data); +await sdk.assets().storeJson(key, { some: 'value' }); +``` + +### Fetching - assets().get() + +```js +const asset = await sdk.assets().get(key); +``` + +Returns the asset with the provided `key`. Returns `null` if not found. + +### Listing - assets().listAll() + +```js +const assets = await sdk.assets().listAll(); +``` + +Returns a list of all assets. Returns `[]` if none. + +### Listing with Prefix - assets().list() + +```js +// list images for a specific user +const prefix = `images/${uid}`; +const assets = await sdk.assets().list(prefix); +``` + +Returns a list of all assets whose keys start with the provided `prefix`. Returns `[]` if none. + +----- +## Authentication Options +There are multiple ways to authenticate to Fleek's endpoints when integrating these storage features into applications, or other projects. + +### Private API Key + +//// Vojtech examples + +### Public API Key (Frontend) + +//// Vojtech examples + +### JWT Custom Token Authentication + +//// Vojtech examples + + +---- +## Application Example - NFTs on IPFS & IC with MetaMask + +We've created an application example to showcase the power of these storage options, and the SDK! + +In this case, we created an NFTs app where users can connect via Metamask, upload NFT content to IPFS and store the CID into an asset canister on the Internet Computer, under the path {ethAddress}/{ipfsHash}.json. Only ethAddress owner will be able to create/update files under that path! + +This example also showcases an example of handling authentication with custom tokens provided by a lambda service. + + +**[See the live application, with live examples here!](https://bafybeigu677y3k6f7ttvpztewk5sbtla4z3tlxvhddzpghjch55ibz4cee.ipfs.dweb.link/)** + diff --git a/mkdocs.yml b/mkdocs.yml index 3e67779..b30dc47 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,8 +40,9 @@ nav: - Fleek Storage: - Overview: storage/overview.md - Storage App: storage/storage-app.md - - Fleek Storage JS: storage/fleek-storage-js.md + - Storage JS (S3 / MinioDB): storage/fleek-storage-js.md - Storage AWS S3 Integration: storage/storage-aws-s3-integration.md + - Fleek SDK (IPFS / IC Storage): storage/fleek-sdk.md - IPFS and IC Gateways: - Overview: gateways/overview.md - Fleek CLI: From b0ff7cccaa1b396a780d53a064423dcd2fa66a9b Mon Sep 17 00:00:00 2001 From: Nico Poggi Date: Tue, 17 Aug 2021 12:07:16 -0400 Subject: [PATCH 2/4] Update fleek-sdk.md --- docs/storage/fleek-sdk.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/storage/fleek-sdk.md b/docs/storage/fleek-sdk.md index 990f5a7..0afe2a6 100644 --- a/docs/storage/fleek-sdk.md +++ b/docs/storage/fleek-sdk.md @@ -94,6 +94,18 @@ const ipfs = sdk.ipfs(); ```js await sdk.ipfs().add(...); ``` + +### Viewing Your Pins on the Fleek App +You can view the IPFS hashes of all your current files pinned to IPFS in the PINNING tab on the Fleek app (app.fleek.co). Log in, and visit this section to view a list of them, and copy the hash if necessary: + +(((IMAGE))) + +This tab is an overview of all the IPFS hashes attached to your account. This includes: + +- Files pinned to IPFS directly using the Fleek SDK. +- Files from sites hosted on IPFS through Fleek. +- Files uploaded to your IPFS storage from the Storage Tab / UI. + ---- ## Storing on the Internet Computer To start using IC Storage, you need to first **go to the Fleek app, visit the Canisters tab and deploy a new Asset Canister**. Fleek will automatically handle the deploy for you. From 0afade869e57557c745e23b1356407cc7434016a Mon Sep 17 00:00:00 2001 From: Nico Poggi Date: Wed, 18 Aug 2021 09:43:18 -0400 Subject: [PATCH 3/4] reword --- docs/storage/fleek-sdk.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/storage/fleek-sdk.md b/docs/storage/fleek-sdk.md index 0afe2a6..0e60c1f 100644 --- a/docs/storage/fleek-sdk.md +++ b/docs/storage/fleek-sdk.md @@ -2,7 +2,7 @@ date: "1" --- -The Fleek SDK is a tool that allows you to interact programmatically with two features on the Fleek platform **IPFS Pinning** and **Internet Computer (IC) Storage**. It is an alternative to the Fleek Storage JS (the Storage JS uses S3/MinioDB to interact with Fleek's Storage/IPFS products, while the Fleek SDK doesn't). +The Fleek SDK is a tool that allows you to interact programmatically with two features on the Fleek platform **IPFS APIs** and **Internet Computer (IC) Storage**. It is an alternative to the Fleek Storage JS and our S3 Storage which uses MinIO to store file metadata (on top of our IPFS storage layer). --- @@ -10,17 +10,17 @@ The Fleek SDK is a tool that allows you to interact programmatically with two fe First, the **IC Storage** tool. Which you can use to deploy asset canisters on the Internet Computer (through Fleek's UI), which you then interact with using this SDK tool to store and fetch files on the Internet Computer. This product and the canister deployment flow can be found in the Fleek App under the **Canisters** tab. -## IPFS Direct Pinning +## Direct Pinning with the IPFS APIs -Secondly, **IPFS Direct Pinning**. This is an alternative to using Fleek's Storage JS. When you store on Fleek's IPFS Storage via the UI, or the Storage JS, you interact with Fleek's IPFS infrastructure through an S3/MinioDB gateway that is on top of it, providing you with human readable live URLs and file metadata that are not native to IPFS. +Secondly, the **IPFS API**. This is an alternative to using Fleek's Storage JS. When you store on Fleek's IPFS Storage via the UI, or the Storage JS, you interact with Fleek's IPFS infrastructure through an S3/MinIO gateway that is on top of it, providing you with human readable live URLs and file metadata that are not native to IPFS. -**Direct Pinning** is an alternative to this, and instead, using the **Fleek SDK** you can store/pin files directly to Fleek's IPFS nodes without going through that centralized layer (S3/MinioDB). +Our S3 Gateways to IPFS use the IPFS APIs underneath, but with the **Fleek SDK** you can use the IPFS APIs directly (like a shortcut!) without interacting with S3. The main benefit of these new APIs is that there is **better regional coverage across the globe**. Instead, you upload files directly using an IPFS client instance in the SDK, and only get the file's IPFS hash. It is a tradeoff approach, where you focus on an IPFS-only more decentralized option, which means your files will only be accessible through interfaces that resolve IPFS hashes (since our S3/MinioDB interface doesn't provide live Web2 URLs for resolving). --- -## Using the IC Storage & Pinning SDK +## Using the Fleek SDK ### Getting the Necessary API Key From 5dd7b46237ffa32e5746441cd66b1d2c33d373fd Mon Sep 17 00:00:00 2001 From: Nico Poggi Date: Wed, 18 Aug 2021 10:23:59 -0400 Subject: [PATCH 4/4] Update fleek-sdk.md --- docs/storage/fleek-sdk.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/storage/fleek-sdk.md b/docs/storage/fleek-sdk.md index 0e60c1f..4ecfaea 100644 --- a/docs/storage/fleek-sdk.md +++ b/docs/storage/fleek-sdk.md @@ -206,5 +206,6 @@ In this case, we created an NFTs app where users can connect via Metamask, uploa This example also showcases an example of handling authentication with custom tokens provided by a lambda service. -**[See the live application, with live examples here!](https://bafybeigu677y3k6f7ttvpztewk5sbtla4z3tlxvhddzpghjch55ibz4cee.ipfs.dweb.link/)** +- **[See the live application, with live examples here!](https://bafybeigu677y3k6f7ttvpztewk5sbtla4z3tlxvhddzpghjch55ibz4cee.ipfs.dweb.link/)** +- **[And check out the source code for this in the SDKs example repo!](https://github.com/FleekHQ/sdk/tree/master/examples/nodejs-ipfs-with-ic-metadata)**