webnative
    TypeScript icon, indicating that this package has built-in type declarations

    0.29.3 • Public • Published

    Webnative SDK

    NPM Build Status License Maintainability Built by FISSION Discord Discourse

    Fission helps developers build and scale their apps. We’re building a web native file system that combines files, encryption, and identity, like an open source iCloud.


    Read the Guide for extended documentation and getting started information.
    The API reference can be found at webnative.fission.app


    What you'll find here

    The Fission webnative SDK offers tools for:

    • authenticating through a Fission authentication lobby
      (a lobby is where you can make a Fission account or link an account)
    • managing your web native file system
      (this is where a user's data lives)
    • tools for building DIDs and UCANs.
    • interacting with the users apps via the platform APIs
    // ES6
    import * as wn from 'webnative'
    
    // Browser/UMD build
    const wn = globalThis.webnative

    Authentication

    const state = await wn.initialise({
      permissions: {
        // Will ask the user permission to store
        // your apps data in `private/Apps/Nullsoft/Winamp`
        app: {
          name: "Winamp",
          creator: "Nullsoft"
        },
    
        // Ask the user permission to additional filesystem paths
        fs: {
          private: [ wn.path.directory("Audio", "Music") ],
          public: [ wn.path.directory("Audio", "Mixtapes") ]
        }
      }
    
    }).catch(err => {
      switch (err) {
        case wn.InitialisationError.InsecureContext:
          // We need a secure context to do cryptography
          // Usually this means we need HTTPS or localhost
    
        case wn.InitialisationError.UnsupportedBrowser:
          // Browser not supported.
          // Example: Firefox private mode can't use indexedDB.
      }
    
    })
    
    
    switch (state.scenario) {
    
      case wn.Scenario.AuthCancelled:
        // User was redirected to lobby,
        // but cancelled the authorisation
        break;
    
      case wn.Scenario.AuthSucceeded:
      case wn.Scenario.Continuation:
        // State:
        // state.authenticated    -  Will always be `true` in these scenarios
        // state.newUser          -  If the user is new to Fission
        // state.throughLobby     -  If the user authenticated through the lobby, or just came back.
        // state.username         -  The user's username.
        //
        // ☞ We can now interact with our file system (more on that later)
        state.fs
        break;
    
      case wn.Scenario.NotAuthorised:
        wn.redirectToLobby(state.permissions)
        break;
    
    }

    redirectToLobby will redirect you to auth.fission.codes our authentication lobby, where you'll be able to make a Fission an account and link with another account that's on another device or browser. The function takes a second, optional, parameter, the url that the lobby should redirect back to (the default is location.href).

    initialise will return a rejected Promise if the browser, or context, is not supported.

    Web Native File System

    The Web Native File System (WNFS) is built on top of the InterPlanetary File System (IPFS). It's 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 publically 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 in such a manner that access to a given folder grants access to all of its subfolders.

    // After initialising …
    const fs = state.fs
    
    // List the user's private files that belong to this app
    await fs.ls(fs.appPath())
    
    // Create a sub directory and add some content
    await fs.write(
      fs.appPath(wn.path.file("Sub Directory", "hello.txt")),
      "👋"
    )
    
    // Announce the changes to the server
    await fs.publish()

    Basics

    WNFS exposes a familiar 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. We don't do this automatically because if you add a large set of data, you only want to do this after everything is added. Otherwise it would be too slow and we would have too many network requests to the API.

    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.

    const file = await fs.get(wn.path.file("private", "Blog Posts", "article.md"))
    
    file.history.list()
    // { delta: -1, timestamp: 1606236743 }
    // { delta: -2, timestamp: 1606236532 }
    
    // Get the previous version
    file.history.back()
    
    // Go back two versions
    const delta = -2
    file.history.back(delta)
    
    // Get the first version (ie. delta -2)
    // by providing a timestamp
    file.history.prior(1606236743)

    Development

    # install dependencies
    yarn
    
    # run development server
    yarn start
    
    # build
    yarn build
    
    # test
    yarn test:prod
    yarn test:unit
    
    # generate docs
    yarn docs
    
    # publish
    yarn publish-latest
    yarn publish-alpha
    

    Install

    npm i webnative

    DownloadsWeekly Downloads

    160

    Version

    0.29.3

    License

    Apache-2.0

    Unpacked Size

    6.08 MB

    Total Files

    375

    Last publish

    Collaborators

    • expede
    • dholms
    • icidasset
    • walkah
    • philipp-fission