akord-js

Akord Client for interacting with Akord.
This package can be used in both browser and Node.js environments.

• Usage
  • Import
  • Quick Start
  • Examples
• Modules
  • Auth
  • Vault
  • Membership
  • Memo
  • Stack
  • File
  • Folder
  • Note
  • Contract
  • Profile
  • Batch
• Development
• Deployment

Usage

requires Node.js 16

Import

import { Akord } from "@akord/akord-js";

or

const { Akord } = require("@akord/akord-js");

Quick start

Init Akord

with email & password

const { akord, wallet, jwtToken } = Akord.auth.signIn(email, password);

with Akord Wallet & JWT

const akord = Akord.init(wallet, jwtToken);

Create vault

const { vaultId } = await akord.vault.create("my first vault");

Upload file to the vault by creating new stack

const { stackId } = await akord.stack.create(vaultId, file, "my first file stack");

Download latest file version of the stack

const { data: fileBuffer, name: fileName } = await akord.stack.getFile(stackId);

Query user vaults

const vaults = await akord.vault.list();

Examples

See our demo app tutorial and learn how to create, contribute and access an Akord Vault.
We also have some example flows in our tests repository.

Modules

auth

signIn(email, password)

• email (string, required)
• password (string, required)
• returns Promise<{ akord, wallet, jwtToken }> - Promise with Akord Client instance, JWT token & Akord Wallet

example

const { akord, wallet, jwtToken } = await akord.auth.signIn("winston@gmail.com", "1984");

signUp(email, password)

• email (string, required)
• password (string, required)
• clientMetadata (any, optional) - JSON client metadata, ex: { clientType: "CLI" }
• returns Promise<AkordWallet> - Promise with Akord Wallet

example

const wallet = await akord.auth.signUp("winston@gmail.com", "1984");

verifyAccount(email, code)

• email (string, required)
• code (string, required)
• returns Promise<void>

example

await akord.auth.verifyAccount("winston@gmail.com", 123456);

vault

create(name, termsOfAccess, isPublic)

• name (string, required) - new vault name
• termsOfAccess (string, optional) - if the vault is intended for professional or legal use, you can add terms of access and they must be digitally signed before accessing the vault
• isPublic (boolean, optional)
• returns Promise<{ vaultId, membershipId, transactionId }> - Promise with new vault id, owner membership id & corresponding transaction id

example

const { vaultId, membershipId } = await akord.vault.create("my first vault", "terms of access");

rename(vaultId, name)

• vaultId (string, required)
• name (string, required) - new vault name
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.vault.rename(vaultId, "updated name");

archive(vaultId)

• vaultId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.vault.archive(vaultId);

restore(vaultId)

• vaultId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.vault.restore(vaultId);

delete(vaultId)

• vaultId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.vault.delete(vaultId);

get(vaultId)

• vaultId (string, required)
• returns Promise<any> - Promise with the decrypted vault

example

const vault = await akord.vault.get(vaultId);

list()

• returns Promise<any> - Promise with currently authenticated user vaults

example

const vaultArray = await akord.vault.list();

membership

invite(vaultId, email, role)

Invite user with an Akord account

• vaultId (string, required)
• email (string, required) - invitee's email
• role (string, required) - CONTRIBUTOR or VIEWER
• returns Promise<{ membershipId, transactionId }> - Promise with new membership id & corresponding transaction id

example

const { membershipId } = await akord.membership.invite(vaultId, "winston@gmail.com", "VIEWER");

inviteNewUser(vaultId, email, role)

Invite user without an Akord account

• vaultId (string, required)
• email (string, required) - invitee's email
• role (string, required) - CONTRIBUTOR or VIEWER
• returns Promise<{ transactionId }> - Promise with new membership id & corresponding transaction id

example

const { membershipId } = await akord.membership.inviteNewUser(vaultId, "winston@gmail.com", "VIEWER");

accept(membershipId)

• membershipId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.membership.accept(membershipId);

confirm(membershipId)

• membershipId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.membership.confirm(membershipId);

reject(membershipId)

Reject pending invitation

• membershipId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.membership.reject(membershipId);

leave(membershipId)

Reject already accepted invitation

• membershipId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.membership.leave(membershipId);

revoke(membershipId)

Revoke a membership, update also each valid membership with new rotated keys

• membershipId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.membership.revoke(membershipId);

changeRole(membershipId, role)

• membershipId (string, required)
• role (string, required) - CONTRIBUTOR or VIEWER
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.membership.changeRole(membershipId, "CONTRIBUTOR");

inviteResend(membershipId)

Resend email invitation

• membershipId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.membership.inviteResend(membershipId);

get(membershipId)

• membershipId (string, required)
• returns Promise<any> - Promise with the decrypted membership

example

const membership = await akord.membership.get(membershipId);

list(vaultId)

• vaultId (string, required)
• returns Promise<any> - Promise with all memberships within given vault

example

const membershipArray = await akord.membership.list(vaultId);

memo

create(vaultId, message)

• vaultId (string, required)
• message (string, required) - memo content
• returns Promise<{ memoId, transactionId }> - Promise with new memo id & corresponding transaction id

example

const { memoId } = await akord.memo.create(vaultId, "Suspendisse ut lorem vitae lectus faucibus lacinia");

addReaction(memoId, reaction)

• memoId (string, required)
• reaction (reactionEmoji, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

import { Akord } from "@akord/akord-js"
// valid values: [JOY, ASTONISHED, CRY, HEART, FIRE, THUMBS_UP, THUMBS_DOWN, PRAY]
const { transactionId } = await akord.memo.addReaction(memoId, Akord.reactionEmoji.FIRE);

removeReaction(memoId, reaction)

• memoId (string, required)
• reaction (reactionEmoji, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

import { Akord } from "@akord/akord-js"
// valid values: [JOY, ASTONISHED, CRY, HEART, FIRE, THUMBS_UP, THUMBS_DOWN, PRAY]
const { transactionId } = await akord.memo.removeReaction(memoId, Akord.reactionEmoji.FIRE);

get(memoId)

• memoId (string, required)
• returns Promise<any> - Promise with the decrypted memo

example

const memo = await akord.memo.get(memoId);

list(vaultId)

• vaultId (string, required)
• returns Promise<any> - Promise with all memos within given vault

example

const memoArray = await akord.memo.list(vaultId);

stack

create(vaultId, file, name, parentId, progressHook, cancelHook)

• vaultId (string, required)
• file (FileLike, required) - file object - web: File, node: NodeJs.File (Blob implementation; web like File)
• name (string, required) - stack name
• parentId (string, optional) - parent folder id
• progressHook ((progress:number)=>void, optional)
• cancelHook (AbortController, optional)
• returns Promise<{ stackId, transactionId }> - Promise with new stack id & corresponding transaction id

example

const { stackId } = await akord.stack.create(vaultId, file, "your stack name");

rename(stackId, name)

• stackId (string, required)
• name (string, required) - new stack name
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.stack.rename(vaultId, "new name for your stack");

uploadRevision(stackId, file, progressHook)

• stackId (string, required)
• file (any, required) - file object
• progressHook ((progress:number)=>void, optional)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.stack.uploadRevision(vaultId, file);

revoke(stackId)

• stackId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.stack.revoke(stackId);

move(stackId, parentId)

• stackId (string, required)
• parentId (string, required) - new parent folder id
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

// create new folder
const { folderId } = await akord.folder.create(vaultId, "new folder");
// move the stack to newly created folder
const { transactionId } = await akord.stack.move(stackId, folderId);

restore(stackId)

• stackId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.stack.restore(stackId);

delete(stackId)

• stackId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.stack.delete(stackId);

get(stackId)

• stackId (string, required)
• returns Promise<any> - Promise with the decrypted stack

example

const stack = await akord.stack.get(stackId);

list(vaultId)

• vaultId (string, required)
• returns Promise<any> - Promise with all stacks within given vault

example

const stackArray = await akord.stack.list(vaultId);

getFile(stackId, index)

Get file stack version by index, return the latest version by default

• stackId (string, required)
• index (string, optional) - file version index
• returns Promise<{ name: string, data: ArrayBuffer }> - Promise with file name & data buffer

example

const { name: fileName, data: fileBuffer } = await akord.stack.getFile(stackId);

file

get(id, vaultId, options)

Returns file as ArrayBuffer. Puts the whole file into memory. For downloading without putting whole file to memory use download()

• id (string, required) - file resource url
• vaultId (string, required)
• options (DownloadOptions, optional)
• returns Promise<ArrayBuffer> - Promise with file buffer

download(id, vaultId, options)

Downloads the file keeping memory consumed (RAM) under defined level: options.chunkSize. In browser, streaming of the binary requires self hosting of mitm.html and sw.js See: https://github.com/jimmywarting/StreamSaver.js#configuration

• id (string, required) - file resource url
• vaultId (string, required)
• options (DownloadOptions, optional)
• returns Promise<ArrayBuffer> - Promise with file buffer

getPublic(id, options)

• id (string, required) - file resource url
• options (DownloadOptions, optional)
• returns Promise<ArrayBuffer> - Promise with file buffer

folder

create(vaultId, name, parentId)

• vaultId (string, required)
• name (string, required) - folder name
• parentId (string, optional) - parent folder id
• returns Promise<{ folderId, transactionId }> - Promise with new folder id & corresponding transaction id

example

const { folderId } = await akord.folder.create(vaultId, "my first folder");

rename(folderId, name)

• folderId (string, required)
• name (string, required) - new folder name
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.folder.rename(folderId, "my first folder");

move(folderId, parentId)

Move the given folder along with its content to a different folder (parent)

• folderId (string, required)
• parentId (string, required) - new parent folder id
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

// create root folder
const rootFolderId = (await akord.folder.create(vaultId, "root folder")).folderId;
// move the folder to newly created root folder
const { transactionId } = await akord.folder.move(folderId, rootFolderId);

revoke(folderId)

Revoke the given folder along with the sub-tree of stacks and folders

• folderId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.folder.revoke(folderId);

restore(folderId)

Restore the given folder along with the sub-tree of stacks and folders

• folderId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.folder.restore(folderId);

delete(folderId)

Remove the folder along with the sub-tree of stacks and folders from the vault

• folderId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.folder.delete(folderId);

get(folderId)

• folderId (string, required)
• returns Promise<any> - Promise with the decrypted folder

example

const folder = await akord.folder.get(folderId);

list(vaultId)

• vaultId (string, required)
• returns Promise<any> - Promise with all folder within given vault

example

const folderArray = await akord.folder.list(vaultId);

note

create(vaultId, name, content, parentId)

• vaultId (string, required)
• name (string, required) - note name
• content (any, required) - JSON note content
• parentId (string, optional) - parent folder id
• returns Promise<{ noteId, transactionId }> - Promise with new note id & corresponding transaction id

example

const { noteId } = await akord.note.create(vaultId, "Hello World note", "# Hello World");

uploadRevision(noteId, name, content)

• noteId (string, required)
• name (string, required) - note name
• content (string, required) - JSON note content
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.note.uploadRevision(vaultId, "Hello World note bis", "# Hello World bis");

move(noteId, parentId)

• noteId (string, required)
• parentId (string, optional) - new parent folder id
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

// create new folder
const { folderId } = await akord.folder.create(vaultId, "new folder");
// move the note to newly created folder
const { transactionId } = await akord.note.move(noteId, folderId);

revoke(noteId)

• noteId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.note.revoke(noteId);

restore(noteId)

• noteId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.note.restore(noteId);

delete(noteId)

• noteId (string, required)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.note.delete(noteId);

get(noteId)

• noteId (string, required)
• returns Promise<any> - Promise with the decrypted note

example

const note = await akord.note.get(noteId);

list(vaultId)

• vaultId (string, required)
• returns Promise<any> - Promise with all notes within given vault

example

const noteArray = await akord.note.list(vaultId);

contract

getState()

• id (string, required) - vault contract id
• returns Promise<Contract> - Promise with the current contract state

example

const currentState = await akord.contract.getState(vaultId);

profile

get()

Fetch currently authenticated user's profile details

• returns Promise<ProfileDetails> - Promise with profile details

update(name, avatar)

Update user profile along with all active memberships

• name (string, required) - new profile name
• avatar (any, required) - new avatar buffer
• returns Promise<Array<{ transactionId }>> - Promise with corresponding transaction ids

batch

revoke(items)

• items (Array<{ transactionId }>, required)
• returns Promise<Array<{ transactionId }>> - Promise with corresponding transaction ids

restore(items)

• items (Array<{ transactionId }>, required)
• returns Promise<Array<{ transactionId }>> - Promise with corresponding transaction ids

delete(items)

• items (Array<{ transactionId }>, required)
• returns Promise<Array<{ transactionId }>> - Promise with corresponding transaction ids

move(items, parentId)

• items (Array<{ transactionId }>, required)
• parentId (string, optional)
• returns Promise<Array<{ transactionId }>> - Promise with corresponding transaction ids

membershipChangeRole(items)

• items (Array<{ transactionId }>, required)
• returns Promise<Array<{ transactionId }>> - Promise with corresponding transaction ids

stackCreate(vaultId, items, parentId, progressHook, cancelHook)

• vaultId (string, required)
• items (Array<{ transactionId }>, required)
• parentId (string, optional)
• progressHook ((progress:number)=>void, optional)
• cancelHook (AbortController, optional)
• returns Promise<Array<{ transactionId }>> - Promise with new stack ids & their corresponding transaction ids

membershipInvite(vaultId, items)

• vaultId (string, required)
• items (Array<{ transactionId }>, required)
• returns Promise<Array<{ transactionId }>> - Promise with new membership ids & their corresponding transaction ids

Development

requires Node.js 16

yarn install
yarn build

To run all tests:

yarn test

To run single test file:

yarn test <path-to-test-file>

yarn test ./src/__tests__/memo.test.ts

To run single test file with direct log output:

node --inspect node_modules/.bin/jest <path-to-test-file>

node --inspect node_modules/.bin/jest ./src/__tests__/folder.test.ts

Deployment

After merging your PR to main:

• go to Actions Tab
• select Start new build workflow
• run Workflow for branch main
  • it will update package version
  • will create a release
  • will build and publish it to NPM