Webnative SDK

This guide is an extended version of the webnative SDK README. You can find the complete API reference at webnative.fission.app.
Have questions? Come join the Fission Discord server or post your question to the Fission Developer forum. We are here to help!
The webnative SDK offers tools for:
Auth. Users make an account and link their account across devices in the Fission auth lobby.
Storage. The webnative file system (WNFS) stores user data for apps.
UCAN and DID tools for working with UCANs and distributed identities
Platform APIs for interacting with user apps
Installation
You can add the webnative SDK to a project by loading it from a CDN or installing it with a package manager.
CDN
For prototyping or experimentation, you can use the latest version of the SDK.
1
<script src="https://unpkg.com/[email protected]/dist/index.umd.js"></script>
Copied!
We recommend linking to a specific version in production to avoid unexpected changes.
Package Manager
We recommend installing with a package manager for larger projects that use build tools or bundlers.
Install the SDK with npm or your preferred package manager.
1
npm install webnative
Copied!
Import the SDK in your application.
1
// ES6
2
import * as wn from 'webnative'
3
​
4
// Browser/UMD build
5
const wn = self.webnative
Copied!
Auth
1
const state = await wn.initialise({
2
  permissions: {
3
    // Will ask the user permission to store
4
    // your apps data in `private/Apps/Nullsoft/Winamp`
5
    app: {
6
      name: "Winamp",
7
      creator: "Nullsoft"
8
    },
9
​
10
    // Ask the user permission for additional filesystem paths
11
    fs: {
12
      privatePaths: [ "Music" ],
13
      publicPaths: [ "Mixtapes" ]
14
    }
15
  }
16
})
17
​
18
​
19
switch (state.scenario) {
20
​
21
  case wn.Scenario.AuthCancelled:
22
    // User was redirected to lobby,
23
    // but cancelled the authorisation
24
    break;
25
​
26
  case wn.Scenario.AuthSucceeded:
27
  case wn.Scenario.Continuation:
28
    // State:
29
    // state.authenticated    -  Will always be `true` in these scenarios
30
    // state.newUser          -  If the user is new to Fission
31
    // state.throughLobby     -  If the user authenticated through the lobby, or just came back.
32
    // state.username         -  The user's username.
33
    //
34
    // ☞ We can now interact with our file system (more on that later)
35
    state.fs
36
    break;
37
​
38
  case wn.Scenario.NotAuthorised:
39
    wn.redirectToLobby(state.permissions)
40
    break;
41
​
42
}
Copied!
redirectToLobby redirects users to our auth lobby at auth.fission.codes, where they can make a Fission account and link their account on another device or in another browser. This function takes an optional parameter, the URL that the lobby should redirect back to (the default is location.href).
Apps request permissions to store user data in a default app storage directory and other public and private directories. Webnative creates these directories for your app if they do not already exist.
File System
The Web Native File System (WNFS) is built on top of the InterPlanetary File System (IPFS). WNFS is structured and functions similarly to a Unix-style file system, with one notable exception: it's a Directed Acyclic Graph (DAG), meaning that a given child can have more than one parent (think symlinks but without the "sym").
Each file system has a public tree and a private tree, much like your macOS, Windows, or Linux desktop file system. The public tree is "live" and publicly accessible on the Internet. The private tree is encrypted so that only the owner can see the contents.
All information (links, data, metadata, etc.) in the private tree is encrypted. Decryption keys are stored so that access to a given folder grants access to all of its subfolders.
1
// After initialising …
2
const fs = state.fs
3
const appPath = fs.appPath()
4
​
5
// List the user's private files that belong to this app
6
await fs.ls(appPath)
7
​
8
// Create a sub directory
9
await fs.mkdir(fs.appPath([ "Sub Directory" ]))
10
await fs.publish()
Copied!
Basics
WNFS exposes a POSIX-style interface:
add: add a file
cat: retrieve a file
exists: check if a file or directory exists
ls: list a directory
mkdir: create a directory
mv: move a file or directory
read: alias for cat
rm: remove a file or directory
write: alias for add
Publish
The publish function synchronises your file system with the Fission API and IPFS. WNFS does not publish changes automatically because it is more practical to batch changes in some cases. For example, a large data set is better published once than over multiple calls to publish.
Returns: CID the updated root CID for the file system
Remember to publish! If you do not call publish after making changes, user data will not be persisted to WNFS.
Versioning
Each file and directory has a history property, which you can use to get an earlier version of that item. We use the delta variable as the order index, primarily because the timestamps can be slightly out of sequence due to device inconsistencies.
1
const file = await fs.get("private/Blog Posts/article.md")
2
​
3
file.history.list()
4
// { delta: -1, timestamp: 1606236743 }
5
// { delta: -2, timestamp: 1606236532 }
6
​
7
// List more than (by default) 5 versions
8
file.history.list(10)
9
​
10
// Get the previous version
11
file.history.back()
12
​
13
// Go back two versions
14
const delta = -2
15
file.history.back(delta)
16
​
17
// Get a version strictly before a timestamp
18
// The first version (delta -2) is prior to
19
// the second version (delta -1) timestamp
20
file.history.prior(1606236743)
Copied!
Requesting many versions with file.history.list can be slow. The acceptable delay will depend on your application. 
API
Methods
Methods for interacting with the filesystem all use absolute paths.
add
Adds some file content at a given path
Params:
path: string required
content: FileContent (object | string | Blob | Buffer) required
Returns: CID the updated root CID for the file system
Example:
1
const content = "hello world"
2
const updatedCID = await fs.add("public/some/path/to/a/file", content)
3
// creates a file called "file" at "public/some/path/to/a"
Copied!
cat
Retrieves some file content at a given path
Params:
path: string required
Returns: FileContent (object | string | Blob | Buffer)
Example:
1
const content = await fs.cat("public/some/path/to/a/file")
Copied!
exists
Checks if there is anything located at a given path
Params:
path: string required
Returns: boolean
Example:
1
const bool = await fs.exists("private/path/to/file")
Copied!
get
Retrieves the node at the given path, either a File or Tree object
Params:
path: string required
Returns: Tree | File | null
Example:
1
const node = await fs.get("public/some/path")
Copied!
ls
Returns a list of links at a given directory path
Params:
path: string required
Returns: { [name: string]: Link } Object with the file name as the key and its Link as the value.
Example:
1
publicLinksObject = await fs.ls("public/some/directory/path") // public
2
privateLinksObject = await fs.ls("private/some/directory/path") // private
3
​
4
// convert private links object to a list
5
links = Object.entries(privateLinksObject)
6
​
7
// working with links
8
data = await Promise.all(links.map(([name, _]) => {
9
  return fs.cat(`private/some/directory/path/${name}`)
10
}))
Copied!
mkdir
Creates a directory at the given path
Params:
path: string required
Returns: CID the updated root CID for the file system
Example:
1
const updatedCID = await fs.mkdir("public/some/directory/path")
2
// creates a directory called "path" at "public/some/directory"
Copied!
mv
Move a directory or file from one path to another
Params:
from: string required
to: string required
Returns: CID the updated root CID for the file system
Example:
1
const updatedCID = await fs.mv("public/doc.md", "private/Documents/notes.md")
Copied!
rm
Removes a file or directory at a given path
Params:
path: string required
Returns: CID the updated root CID for the file system
Example:
1
const updatedCID = await fs.rm("private/some/path/to/a/file")
Copied!
write
Alias for add.
Params:
path: string required
content: FileContent (object | string | Blob | Buffer) required
Returns: CID the updated root CID for the file system
Example:
1
const content = "hello world"
2
const updatedCID = await fs.write("public/some/path/to/a/file", content)
Copied!
Apple Silicon (M1) Macs
Additional information
Last modified 1yr ago
Export as PDF
Copy link
Contents