@akord/akord-js

akord-js

Akord Client - a set of core js functions to interact with Akord.
This package can be used in both browser and Node.js environments.

• Usage
  • Import
  • Quick Start
  • Plugins
  • Examples
• Modules
  • Auth
  • Vault
  • Membership
  • Memo
  • Stack
  • Folder
  • Note
  • Manifest
  • NFT
  • Collection
  • Contract
  • Profile
  • Batch
  • Zip
  • Storage
• Development
• Deployment

Usage

requires Node.js >= 18

Import

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

or

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

Quick start

Init Akord

import { Akord, Auth } from "@akord/akord-js";
const { wallet } = await Auth.signIn(email, password);
const akord = new Akord(wallet);

Create vault

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

Upload file to the vault by creating new stack

const { stackId, uri } = await akord.stack.create(vaultId, file);
// Once the transaction is accepted on Arweave network (it takes 5-15 minutes on average),
// you can access your file on ViewBlock by visiting the following URL: https://viewblock.io/arweave/tx/{uri}

Download latest file version of the stack

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

Query user vaults

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

Plugins

Some methods require plugins installation. This design is motivated by bundle size care: increase the package bundle size only if feature is used. Official supported plugins can be found at: plugins

import { PubSubPlugin } from "@akord/akord-js-pubsub-plugin"
import { Akord, Auth } from "@akord/akord-js";

const { wallet } = await Auth.signIn('your_username', 'your_password');
const akord = new Akord(wallet, { plugins: [new PubSubPlugin()] });

Examples

• See our demo app tutorial and learn how to create, contribute and access an Akord Vault from.

• See example flows under tests.

• See different setups under examples.

Authentication

Use Auth module to handle authentication.

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

• By default Auth is using SRP authentication
• Auth stores tokens in Storage implementation
• Storage defaults to localStorage on web & memoryStorage on nodeJs
• Storage implementation can be configured with Auth.configure({ storage: window.sessionStorage })
• Auth is automatically refreshing tokens in SRP mode
• On server side it is recommended to use API keys: Auth.configure({ apiKey: 'your_api_key' })
• API key: can be generated over web app & over CLI

use short living token with refresh

import { Auth } from "@akord/akord-js";
Auth.configure({ storage: window.sessionStorage }); // optionally - configure tokens store

use API key

import { Auth } from "@akord/akord-js";
Auth.configure({ apiKey: "api_key" });

use self-managed auth token

import { Akord, Auth } from "@akord/akord-js";
Auth.configure({ authToken: "auth_token" });

signIn(email, password)

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

example

const { wallet } = await Auth.signIn("[e-mail]", "1984");

signUp(email, password)

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

example

const { wallet } = await Auth.signUp("[e-mail]", "1984");

verifyAccount(email, code)

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

example

await Auth.verifyAccount("[e-mail]", 123456);

Modules

vault

create(name, options)

• name (string, required) - new vault name
• options (VaultCreateOptions, optional) - public/private, terms of access, etc.
• returns Promise<{ vaultId, membershipId, transactionId }> - Promise with new vault id, owner membership id & corresponding transaction id

example

// create a private vault
const { vaultId, membershipId } = await akord.vault.create("my first private vault");

// create a public vault with terms of access
const { vaultId, membershipId } = await akord.vault.create(
  "my first public vault",
  { public: true, termsOfAccess: "terms of access here - 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" }
);

// create a public vault with description & tags for easier lookup
const { vaultId, membershipId } = await akord.vault.create("Arty podcast", {
    public: true,
    description: "A permanent podcast dedicated to art history",
    tags: ["art", "podcast", "archive"]
  });

// create a cloud storage vault 
const { vaultId, membershipId } = await akord.vault.create("Non permanent stuff", {
    cloud: true
  });

update(vaultId, options)

• vaultId (string, required)
• options (VaultUpdateOptions, required) - name, description & tags
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.vault.update(vaultId, {
  name: "color palette",
  description: "color inspiration for design and art projects",
  tags: ["taupe", "burgundy", "mauve"]
});

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");

addTags(vaultId, tags)

• vaultId (string, required)
• tags (string[], required) - tags to be added
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.vault.addTags(vaultId, ["taupe", "burgundy"]);

removeTags(vaultId, tags)

• vaultId (string, required)
• tags (string[], required) - tags to be removed
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.vault.removeTags(vaultId, ["taupe", "burgundy"]);

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, options)

• vaultId (string, required)
• options (VaultGetOptions, optional)
• returns Promise<Vault> - Promise with the vault object

example

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

listAll(options)

• options (ListOptions, optional)
• returns Promise<Array<Vault>> - Promise with currently authenticated user vaults

example

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

list(listOptions)

• options (ListOptions, optional)
• returns Promise<{ items, nextToken }> - Promise with paginated user vaults

example

// retrieve first 100 user vaults
const { items } = await akord.vault.list();

// retrieve first 20 user vaults
const { items } = await akord.vault.list({ limit: 20 });

// iterate through all user vaults
let token = null;
let vaults = [];
do {
  const { items, nextToken } = await akord.vault.list({ nextToken: token });
  vaults = vaults.concat(items);
  token = nextToken;
} while (token);

membership

invite(vaultId, email, role)

Invite user with an Akord account

• vaultId (string, required)
• email (string, required) - invitee's email
• role (RoleType, required) - VIEWER/CONTRIBUTOR/OWNER
• options (MembershipCreateOptions, optional) - invitation email message, etc.
• returns Promise<{ membershipId, transactionId }> - Promise with new membership id & corresponding transaction id

example

const { membershipId } = await akord.membership.invite(vaultId, "[e-mail]", "VIEWER");

inviteNewUser(vaultId, email, role)

Invite user without an Akord account

• vaultId (string, required)
• email (string, required) - invitee's email
• role (RoleType, required) - VIEWER/CONTRIBUTOR/OWNER
• options (MembershipCreateOptions, optional) - invitation email message, etc.
• returns Promise<{ transactionId }> - Promise with new membership id & corresponding transaction id

example

const { membershipId } = await akord.membership.inviteNewUser(vaultId, "[e-mail]", "VIEWER");

airdrop(vaultId, members)

Airdrop access to the vault to the batch of public keys. New members can access/contribute the vault using their private/public key pair.
NOTE: If the new members are contributors, what they contribute is under the domain of the vault owner.

example

import { Akord, Auth } from "@akord/akord-js";
import { AkordWallet } from "@akord/crypto";

const wallet1 = await AkordWallet.create();
const wallet2 = await AkordWallet.create();
const wallet3 = await AkordWallet.create();
const wallet4 = await AkordWallet.create();

const tomorrowSameHour = new Date(new Date().getTime() + 24 * 60 * 60 * 1000);
const inOneMinute = new Date(new Date().getTime() + 60 * 1000);

await akord.membership.airdrop(vaultId, [
   { 
    publicSigningKey: wallet1.signingPublicKey(), 
    publicKey: wallet1.publicKey(), 
    role: "VIEWER", // view only access to vault
    options: {
      expirationDate: tomorrowSameHour // access valid for 24 hours
    }
   },
   { 
    publicSigningKey: wallet2.signingPublicKey(), 
    publicKey: wallet2.publicKey(), 
    role: "CONTRIBUTOR", // can edit / add / delete
    options: {
      expirationDate: inOneMinute, // access valid for 1 minute
      allowedStorage: 10 // can use up to 10Mb from host account
    }
   },
   { 
    publicSigningKey: wallet3.signingPublicKey(), 
    publicKey: wallet3.publicKey(), 
    role: "CONTRIBUTOR",
    options: {
      expirationDate: null, // valid until manual revoke
      allowedStorage: 0 // can't upload (but can edit e.g. move, rename)
    }
   },
   { 
    publicSigningKey: wallet4.signingPublicKey(), 
    publicKey: wallet4.publicKey(), 
    role: "CONTRIBUTOR",
    options: {
      allowedStorage: null // can upload using full storage balance of the host
    }
   }
]);

// access the vault as user 1
await Auth.signInWithWallet(wallet1);
const akord1 = new Akord(wallet1);
console.log(await akord1.vault.get(vaultId));

// access the vault as user 2
await Auth.signInWithWallet(wallet2);
const akord2 = new Akord(wallet2);
console.log(await akord2.vault.get(vaultId));

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 (RoleType, required) - VIEWER/CONTRIBUTOR/OWNER
• 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, options)

• membershipId (string, required)
• options (GetOptions, optional)
• returns Promise<Membership> - Promise with the membership object

example

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

listAll(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<Array<Membership>> - Promise with all memberships within given vault

example

const memberships = await akord.membership.listAll(vaultId);

list(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<{ items, nextToken }> - Promise with paginated memberships within given vault

example

// retrieve first 100 memberships for the vault
const { items } = await akord.membership.list(vaultId);

// retrieve first 20 memberships for the vault
const { items } = await akord.membership.list(vaultId, { limit: 20 });

// iterate through all memberships
let token = null;
let memberships = [];
do {
  const { items, nextToken } = await akord.membership.list(vaultId, { nextToken: token });
  memberships = memberships.concat(items);
  token = nextToken;
} while (token);

memo

create(vaultId, message)

• vaultId (string, required)
• message (string, required) - memo content
• options (NodeCreateOptions, optional) - parent id, etc.
• 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, options)

• memoId (string, required)
• options (GetOptions, optional)
• returns Promise<Memo> - Promise with the memo object

example

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

listAll(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<Array<Memo>> - Promise with all memos within given vault

example

const memos = await akord.memo.listAll(vaultId);

list(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<{ items, nextToken }> - Promise with paginated memos within given vault

example

// retrieve first 100 memos for the vault
const { items } = await akord.memo.list(vaultId);

// retrieve first 20 memos for the vault
const { items } = await akord.memo.list(vaultId, { limit: 20 });

// iterate through all memos
let token = null;
let memos = [];
do {
  const { items, nextToken } = await akord.memo.list(vaultId, { nextToken: token });
  memos = memos.concat(items);
  token = nextToken;
} while (token);

stack

create(vaultId, file, name)

• vaultId (string, required)
• file (FileSource, required) - file source: web File object, file path, buffer or stream
• name (string, required) - stack name
• options (StackCreateOptions, optional)
• returns Promise<{ stackId, transactionId }> - Promise with new stack id & corresponding transaction id

example

// create a stack from file path with custom arweave tags
const { stackId, uri } = await akord.stack.create(vaultId, "path to your file", {
   arweaveTags: [
      { name: "Type", value: "music" },
      { name: "Genre", value: "rock" },
      { name: "Genre", value: "new wave" }
   ]
});
// Once the transaction is accepted on Arweave network (it takes 5-15 minutes on average),
// you can access your file on ViewBlock by visiting the following URL: https://viewblock.io/arweave/tx/{uri}

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

// create a file stack with UDL

// first let's define terms of UDL
const udl = {
  license: UDL_LICENSE_TX_ID,
  licenseFee: {
    type: "Monthly",
    value: 5
  },
  derivations: [
    {
      type: "Allowed-With-RevenueShare",
      value: 30,
    },
    {
      type: "Allowed-With-RevenueShare",
      value: 10,
      duration: {
        type: "After",
        value: 2
      }
    }
  ],
  commercialUses: [{ type: "Allowed-With-Credit" }],
  paymentAddress: "89tR0-C1m3_sCWCoVCChg4gFYKdiH5_ZDyZpdJ2DDRw"
};
// then pass it as an option when creating the file stack
const { stackId } = await akord.stack.create(vaultId, file, { udl: udl });

See Next.js file upload showcase here

import(vaultId, fileTxId)

Create new stack from an existing arweave file transaction

• vaultId (string, required)
• fileTxId (string, required) - arweave file transaction id reference
• options (NodeCreateOptions, optional) - parent id, etc.
• returns Promise<{ stackId, transactionId }> - Promise with new stack id & corresponding transaction id

example

const { stackId } = await akord.stack.import(vaultId, "kzGxbFW_oJ3PyYneRs9cPrChQ-k-8Fym5k9PCZNJ_HA");

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(stackId, "new name for your stack");

uploadRevision(stackId, file)

• stackId (string, required)
• file (FileSource, required) - file source: web File object, file path, buffer or stream
• options (FileUploadOptions, optional)
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.stack.uploadRevision(stackId, "path to your 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, options)

• stackId (string, required)
• options (GetOptions, optional)
• returns Promise<Stack> - Promise with the stack object

example

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

listAll(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<Array<Stack>> - Promise with all stacks within given vault

example

const stacks = await akord.stack.listAll(vaultId);

list(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<{ items, nextToken }> - Promise with paginated stacks within given vault

example

// retrieve first 100 stacks for the vault
const { items } = await akord.stack.list(vaultId);

// retrieve first 20 stacks for the vault
const { items } = await akord.stack.list(vaultId, { limit: 20 });

// iterate through all stacks
let token = null;
let stacks = [];
do {
  const { items, nextToken } = await akord.stack.list(vaultId, { nextToken: token });
  stacks = stacks.concat(items);
  token = nextToken;
} while (token);

getVersion(stackId, index)

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

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

example

// get the latest stack version
const { name: fileName, data: fileBuffer } = await akord.stack.getVersion(stackId);

// get the first stack version
const { name: fileName, data: fileBuffer } = await akord.stack.getVersion(stackId, 0);

getUri(stackId, type, index)

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

• stackId (string, required)
• type (StorageType, optional) - storage type, default to arweave
• index (number, optional) - file version index, default to latest
• returns Promise<string> - Promise with stack file uri

example

// get the arweave uri for the latest file version
const arweaveUri = await akord.stack.getUri(stackId);

// get the arweave uri for the first file version
const arweaveUri = await akord.stack.getUri(stackId, 0);

download(stackId, index, options)

Download stack version by index, return the latest version by default. This method can be used for downloading the binary or previewing it in browser (use options.noSave).

• stackId (string, required)
• index (number, optional) - file version index, default to latest
• options (FileDownloadOptions], optional) - control download behavior
• returns Promise<string> - Promise with location of downloaded file

example

    
  // download the file in browser / on server:
  await akord.stack.download(stackId, index)
    
  // preview the file in browser:
  const url = await akord.stack.download(stackId, index, { skipSave: true })
       
  <video src={url} controls />  

folder

create(vaultId, name)

• vaultId (string, required)
• name (string, required) - folder name
• options (NodeCreateOptions, optional) - parent id, etc.
• 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, options)

• folderId (string, required)
• options (GetOptions, optional)
• returns Promise<Folder> - Promise with the folder object

example

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

listAll(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<Array<Folder>> - Promise with all folders within given vault

example

const folders = await akord.folder.listAll(vaultId);

list(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<{ items, nextToken }> - Promise with paginated folders within given vault

example

// retrieve first 100 folders for the vault
const { items } = await akord.folder.list(vaultId);

// retrieve first 20 folders for the vault
const { items } = await akord.folder.list(vaultId, { limit: 20 });

// iterate through all folders
let token = null;
let folders = [];
do {
  const { items, nextToken } = await akord.folder.list(vaultId, { nextToken: token });
  folders = folders.concat(items);
  token = nextToken;
} while (token);

note

create(vaultId, content, name)

• vaultId (string, required)
• content (string, required) - note text content, ex: stringified JSON
• name (string, required) - note name
• options (NoteCreateOptions, optional) - parent id, mime type, etc.
• returns Promise<{ noteId, transactionId }> - Promise with new note id & corresponding transaction id

example

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

const { noteId } = await akord.note.create(
  vaultId,
  JSON.stringify({ name: "My first JSON note" }),
  "My first JSON note",
  { parentId: parentId, mimeType: "application/json" }
);

uploadRevision(noteId, content, name)

• noteId (string, required)
• content (string, required) - note text content, ex: stringified JSON
• name (string, required) - note name
• options (NoteOptions, optional) - mime type, etc.
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

const { transactionId } = await akord.note.uploadRevision(noteId, "# Hello World bis", "Hello World note 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, options)

• noteId (string, required)
• options (GetOptions, optional)
• returns Promise<Note> - Promise with the note object

example

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

listAll(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<Array<Note>> - Promise with all notes within given vault

example

const notes = await akord.note.listAll(vaultId);

list(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<{ items, nextToken }> - Promise with paginated notes within given vault

example

// retrieve first 100 notes for the vault
const { items } = await akord.note.list(vaultId);

// retrieve first 20 notes for the vault
const { items } = await akord.note.list(vaultId, { limit: 20 });

// iterate through all notes
let token = null;
let notes = [];
do {
  const { items, nextToken } = await akord.note.list(vaultId, { nextToken: token });
  notes = notes.concat(items);
  token = nextToken;
} while (token);

getVersion(noteId, index)

Get note text version by index, return the latest version by default

• noteId (string, required)
• index (number, optional) - note version index
• returns Promise<{ name: string, data: string }> - Promise with note name & data string text

example

// get the latest note version
const { name: fileName, data: noteText } = await akord.note.getVersion(noteId);

// get the first note version
const { name: fileName, data: noteText } = await akord.note.getVersion(noteId, 0);

manifest

Manifest is a special case of Stack that is unique per vault and follows Arweave Path Manifest standard.

generate(vaultId)

If there is no manifest for the vault, a new manifest stack will be created, otherwise a new version of the manifest will be generated and uploaded.

If no input JSON is provided by the user, manifest will be generated automatically from the current vault/folder state.

• vaultId (string, required)
• options (ManifestOptions, optional) - parent id, custom index, manually created manifest, etc.
• returns Promise<{ transactionId }> - Promise with corresponding transaction id

example

// generate manifest for the entire vault contents
const { uri } = await akord.manifest.generate(vaultId);
console.log("Manifest link: https://arweave.net/" + uri);

// generate manifest for a specific folder
const { uri } = await akord.manifest.generate(vaultId, { parentId: folderId });
console.log("Manifest link: https://arweave.net/" + uri);

get(vaultId)

• vaultId (string, required)
• returns Promise<Stack> - Promise with the vault manifest object

example

const manifestNode = await akord.manifest.get(vaultId);

getVersion(vaultId, index)

Get vault manifest version by index, return the latest version by default

• vaultId (string, required)
• index (number, optional) - file version index
• returns Promise<JSON> - Promise with JSON manifest

example

// get the latest vault manifest
const manifest = await akord.manifest.getVersion(vaultId);

// get the first version of the vault manifest
const manifestV1 = await akord.manifest.getVersion(vaultId, 0);

nft

The NFT module enables the creation of atomic NFTs compliant with the Atomic Asset standard.

The atomic asset can be minted with the option to attach the Universal Data License (UDL), and can be listed on the Universal Content Marketplace (UCM).

mint(vaultId, asset, metadata, options)

• vaultId (string, required)
• asset (FileSource, required) - asset data
• metadata (NFTMetadata, required) - NFT metadata: name, ticker, description, owner, creator, etc.
• options (NFTMintOptions, optional) - ex: UDL terms
• returns Promise<{ nftId, transactionId, uri }> - Promise with new nft id & corresponding transaction id

example

// Mint an atomic NFT with the UDL attached

// First, let's define our NFT metadata
const nftMetadata = {
  name: "Golden Orchid - Flora Fantasy #1",
  creator: "VALID_ARWEAVE_ADDRESS",
  owner: "VALID_ARWEAVE_ADDRESS",
  collection: "Flora Fantasy",
  description: "A rare digital representation of the mythical Golden Orchid",
  types: ["image"],
  topics: ["floral", "nature"]
};

// Then, let's define UDL terms
const udlTerms = {
  licenseFee: {
    type: "One-Time",
    value: 10
  },
  derivations: [{ type: "Allowed-With-Credit" }]
};

// Finally, let's mint the NFT by passing the path to the asset data, NFT metadata, and UDL terms
const { uri } = await akord.nft.mint(vaultId, "./your-nft.jpeg", nftMetadata, { udl: udlTerms });

// Once the transaction is accepted on Arweave network (it takes 5-15 minutes on average),
// you can access your NFT on ViewBlock by visiting the following URL:
// https://viewblock.io/arweave/tx/{uri}

get(nftId, options)

• nftId (string, required)
• options (GetOptions, optional)
• returns Promise<NFT> - Promise with the nft object

example

const nft = await akord.nft.get(nftId);

listAll(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<Array<NFT>> - Promise with all nfts within given vault

example

const nfts = await akord.nft.listAll(vaultId);

list(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<{ items, nextToken }> - Promise with paginated nfts within given vault

example

// retrieve first 100 nfts for the vault
const { items } = await akord.nft.list(vaultId);

// retrieve first 20 nfts for the vault
const { items } = await akord.nft.list(vaultId, { limit: 20 });

getAsset(nftId)

Get nft asset

• nftId (string, required)
• returns Promise<{ data: ArrayBuffer } & FileVersion> - Promise with nft asset object & data buffer

example

// get nft data buffer
const { data: fileBuffer } = await akord.nft.getAsset(nftId);

getUri(nftId, type)

Get nft asset uri

• nftId (string, required)
• type (StorageType, optional) - storage type, default to arweave
• returns Promise<string> - Promise with nft asset uri

example

// get the arweave uri for the nft asset
const arweaveUri = await akord.nft.getUri(nftId);

collection

The collection module enables the creation of a collection of NFTs compliant with the Collection protocol.

mint(vaultId, asset, metadata, options)

NOTE: each NFT will inherit collection metadata setup

• vaultId (string, required)
• items ({asset:FileSource,metadata:NFTMetadata,options:NFTMintOptions}[], required) - items to mint
• metadata (CollectionMetadata, required) - Collection metadata: name, ticker, description, owner, creator, etc.
• options (CollectionMintOptions, optional) - ex: UDL terms
• returns Promise<{ collectionId, transactionId, items }> - Promise with new collection id, minted NFTs & corresponding transaction id

example

// First, let's define our Collection metadata
const collectionMetadata = {
  name: "Flora Fantasy",
  creator: "VALID_ARWEAVE_ADDRESS", // should be a valid Arweave address
  owner: "VALID_ARWEAVE_ADDRESS", // should be a valid Arweave address
  description: "Discover the enchanting world of Flora Fantasy, where nature meets fantasy in mesmerizing digital artworks",
  types: ["image", "collection"],
  topics: ["floral", "nature"]
};

// Then, let's define UDL terms for the whole collection
const udlTerms = {
  licenseFee: {
    type: "One-Time",
    value: 10
  },
  derivations: [{ type: "Allowed-With-Credit" }]
};

// Finally, let's mint the collection & list it on UCM
const { uri, items } = await akord.collection.mint(
  vaultId,
  [{ asset: file, metadata: { name: "Golden Orchid #1" } }],
  collectionMetadata,
  { udl: udl, ucm: true }
);
// Once the transaction is accepted on Arweave network (it takes 5-15 minutes on average),
// you can view your collection on BazAR by visiting the following URL:
// https://bazar.arweave.dev/#/collection/{uri}

get(collectionId, options)

• collectionId (string, required)
• options (GetOptions, optional)
• returns Promise<Collection> - Promise with the collection object

example

const collection = await akord.collection.get(collectionId);

listAll(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<Array<Collection>> - Promise with all collections within given vault

example

const collections = await akord.collection.listAll(vaultId);

list(vaultId, options)

• vaultId (string, required)
• options (ListOptions, optional)
• returns Promise<{ items, nextToken }> - Promise with paginated collections within given vault

example

// retrieve first 100 collections for the vault
const { items } = await akord.collection.list(vaultId);

// retrieve first 20 collections for the vault
const { items } = await akord.collection.list(vaultId, { limit: 20 });

getBanner(collectionId)

Get collection banner

• collectionId (string, required)
• returns Promise<{ data: ArrayBuffer } & FileVersion> - Promise with collection banner

example

// get collection banner buffer
const { data: fileBuffer } = await akord.collection.getBanner(collectionId);

getThumbnail(collectionId)

Get collection thumbnail

• collectionId (string, required)
• returns Promise<{ data: ArrayBuffer } & FileVersion> - Promise with collection thumbnail

example

// get collection thumbnail buffer
const { data: fileBuffer } = await akord.collection.getThumbnail(collectionId);

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 (ArrayBuffer, required) - new avatar buffer
• returns Promise<Array<{ transactionId }>> - Promise with corresponding transaction ids

batch

revoke(items)

• items (Array<{ id: string, type: NodeType }>, required)
• returns Promise<Array<{ transactionId }>> - Promise with corresponding transaction ids

restore(items)

• items (Array<{ id: string, type: NodeType }>, required)
• returns Promise<Array<{ transactionId }>> - Promise with corresponding transaction ids

delete(items)

• items (Array<{ id: string, type: NodeType }>, required)
• returns Promise<Array<{ transactionId }>> - Promise with corresponding transaction ids

move(items, parentId)

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

membershipChangeRole(items)

• items (Array<{ id: string, role: RoleType }>, required)
• returns Promise<Array<{ transactionId }>> - Promise with corresponding transaction ids

stackCreate(vaultId, items)

• vaultId (string, required)
• items (Array<{ file: FileSource, name: string, options: StackCreateOptions>, required)
• options (BatchStackCreateOptions, optional)
• returns Promise<BatchStackCreateResponse> - Promise with new stack ids & their corresponding transaction ids

membershipInvite(vaultId, items)

• vaultId (string, required)
• items (Array<{ email: string, role: RoleType }>, required)
• options (MembershipCreateOptions, optional) - invitation email message, etc.
• returns Promise<BatchMembershipInviteResponse> - Promise with new membership ids & their corresponding transaction ids

zip

list(options)

• options (ListOptions, optional)
• returns Promise<{ items, nextToken }> - Promise with paginated zips uploaded by user

example

// retrieve first 100 zips for given user
const { items } = await akord.zip.list();

// retrieve first 20 zips for given user
const { items, nextToken } = await akord.zip.list({ limit: 20 });
// retrieve next 10 zips for given user
const { items } = await akord.zip.list({ limit: 10, nextToken: nextToken });

listAll(options)

• options (ListOptions, optional)
• returns Promise<Array<ZipLog>> - Promise with all zip logs for given account

example

const zips = await akord.zip.listAll();

upload(vaultId, file, options)

• vaultId (string, required)
• file (FileSource, required) - file source: web File object, file path, buffer or stream
• options (ZipUploadOptions, optional)
• returns Promise<{ sourceId }> - Promise with corresponding source id, allowing to query corresponding files

example

const { sourceId } = await akord.zip.upload(vaultId, "path to your file");

storage

get()

• returns Promise<Storage> - Promise with user storage balance

example

const storage = await akord.storage.get();

buy()

Pay for storage. Increases Permanent Storage balance

• returns Promise<StorageBuyResponse> - Promise with price amount & currencyCode. Contains paymentId for non sumulated payments.

example

const gigabytesToBuy = 2;
const { amount, currencyCode } = await akord.storage.buy(gigabytesToBuy, { simulate: true }); // no actual payment, just check price

example

const { paymentId, amount, currencyCode } = await akord.storage.buy(3); // initiate payment for 3 GB's: no storage increase yet, no payment yet

await akord.storage.buy({ paymentId }); // confirm the payment: storage increase after successful payment

example

const { paymentId, amount, currencyCode } = await akord.storage.buy(3, { currencyCode: 'EUR', confirm: true }); // auto-confirm payment for 3 GB's: storage increase after successful payment

Development

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