JavaScript SDK

This package is written in Typescript.

Installation

npm i jsonbank
# OR YARN
yarn add jsonbank

Initialize

JsonBank class can be initialized with or without api keys.
Api Keys are only required when you want to access private/secured documents

Without Api Keys

const {JsonBank} = require("jsonbank")

const jsb = new JsonBank();

With Api Keys

const {JsonBank} = require("jsonbank")

// Initialize with Api keys.
const jsb = new JsonBank({
  keys: {
    pub: 'JSB_PUBLIC_KEY',
    prv: 'JSB_PRIVATE_KEY',
  }
});

// authenticate the api keys
await jsb.authenticate();

Public Api Key

A read-only key. Use it to authenticate() and to read your own private documents. Public documents need no key at all.

Private Api Key

A write-only key, only needed to create, update or delete documents.

Check Authentication

To check if the user is authenticated, use the isAuthenticated method.
Make sure to have called authenticate method before.

await jsb.authenticate();

// check if the user is authenticated
jsb.isAuthenticated() // true

Public Content Methods

Public contents do not require authentication.

getDocumentMeta()

Get a public document meta details either by id or path. Does not return the content of the document. To get the content, use getContent method.

Code

const meta = await jsb.getDocumentMeta("jsonbank/sdk-test/index");
// result is of type "JSB_Response.ContentMeta"
console.log(meta.id) // id of the document
console.log(meta.project) // project name
console.log(meta.name) // name of the document
console.log(meta.contentSize) // size object of the document
console.log(meta.path) // path of the document
console.log(meta.updatedAt) // date of last update
console.log(meta.createdAt) // date of creation

Result

type ContentMeta = {
  id: string;
  project: string;
  contentSize: {
    number: number;
    string: string;
  };
  path: string;
  name: string;
  folderId?: string;
  updatedAt: string;
  createdAt: string;
};

getContent()

Get a public document content either by id or path. It returns the json parsed object. You can also pass a query to shape what you get back.

Code

const content = await jsb.getContent("jsonbank/sdk-test/index");
// content is a json object

Result

{
  "name": "JsonBank SDK Test File",
  "author": "jsonbank"
}

getContentAsString()

Get a public document content either by id or path as a string. It returns a string.

const content = await jsb.getContentAsString("jsonbank/sdk-test/index");
// content is a string

getGithubContent()

Grab a public json file from Github. This will read from the default branch of the repo.
It returns the json parsed object.

Note: Referenced file must be a public json file.

Code

await jsb.getGithubContent("org/repo/file.json");

// example
await jsb.getGithubContent("jsonbankio/documentation/github-test.json")

Result

{
  "name": "github-test.json",
  "purpose": "This file is used to test the github json fetcher"
}

getGithubContentAsString()

Same as getGithubContent but returns the content as a string.

Note: Referenced file must be a public json file.

Code

await jsb.getGithubContentAsString("org/repo/file.json");

// example
await jsb.getGithubContentAsString("jsonbankio/documentation/github-test.json")

Result

{"name": "github-test.json", "purpose": "This file is used to test the github json fetcher"}

Filtering Content (JSBQuery)

The read methods (getContent, getOwnContent, getGithubContent) take an optional query as their second argument. A query tells jsonbank to transform the json before sending it back, so you only get the data you need.

How filtering works

A query is an object with an apply modifier and optional args.

type JSBQuery = {
  apply: string; // the modifier to run e.g "pick", "get"
  args?: string | string[];
};

Pass a single query, or an array of queries to run them one after another.

Example: pick

Pick only the fields you want.

Code

const content = await jsb.getContent("jsonbank/sdk-test/index", {
  apply: "pick",
  args: ["name"]
});

Result

{
  "name": "JsonBank SDK Test File"
}

Example: get

Grab a single value by its key.

Code

const name = await jsb.getContent("jsonbank/sdk-test/index", {
  apply: "get",
  args: "name"
});

Result

"JsonBank SDK Test File"

Available modifiers

Modifiers mirror their lodash counterparts:

chunk, first, last, nth, reverse, slice, take, takeRight, mapPick, mapOmit, get, at, has, hasIn, keys, values, valuesIn, keysIn, omit, unset, pick, castArray, isArray, find, findLast, filter, size, every, orderBy, sortBy, reject, shuffle, map, max, min, sum.

Access Own Content

Your own content is the documents in your projects. To read them, initialize with your api keys and authenticate first. See With Api Keys for more details.

Note: These methods need your public api key. Call authenticate() before using them.

getOwnContent()

Get one of your documents either by id or path. Works for private documents too. It returns the json parsed object.

const content = await jsb.getOwnContent("sdk-test/index");
// content is a json object

getOwnContentAsString()

Same as getOwnContent but returns the content as a string.

const content = await jsb.getOwnContentAsString("sdk-test/index");
// content is a string

getOwnDocumentMeta()

Get the meta of one of your documents either by id or path. Returns the same ContentMeta type as getDocumentMeta.

const meta = await jsb.getOwnDocumentMeta("sdk-test/index");
// result is of type "JSB_Response.ContentMeta"

hasOwnDocument()

Check if one of your documents exists, either by id or path.

await jsb.hasOwnDocument("sdk-test/index"); // true
await jsb.hasOwnDocument("does-not-exist"); // false

Note: Returns false instead of throwing when the document is not found.

Managing Content

Create, update and delete documents in your projects.

Note: These methods need your private api key.

createDocument()

Create a new document in a project. folder is optional, leave it out to create at the project root. content can be an object or a json string.

Code

const doc = await jsb.createDocument({
  name: "new_doc",
  project: "sdk-test",
  folder: "folder", // optional
  content: {
    name: "new_doc",
    created: new Date().toISOString()
  }
});

Result

type NewDocument = {
  id: string;
  name: string;
  path: string;
  project: string;
  createdAt: string;
};

createDocumentIfNotExists()

Same as createDocument, but if the document already exists it is fetched and returned instead of throwing.

const doc = await jsb.createDocumentIfNotExists({
  name: "index.json",
  project: "sdk-test",
  content: { name: "JsonBank SDK Test File", author: "jsonbank" }
});

// when it already existed
doc.exists // true

updateOwnDocument()

Update the content of one of your documents either by id or path. content can be an object or a json string.

Code

const result = await jsb.updateOwnDocument("sdk-test/index", {
  name: "JsonBank SDK Test File",
  author: "jsonbank",
  updatedAt: new Date().toISOString()
});

result.changed // true

Result

{
  id: string;
  changed: boolean;
  message: string;
}

deleteDocument()

Delete one of your documents either by id or path.

await jsb.deleteDocument("sdk-test/folder/new_doc");
// { deleted: true }

Note: Returns { deleted: false } instead of throwing when the document is not found.

Folders

Group documents into folders inside a project.

getFolder()

Get a folder either by id or path.

Code

const folder = await jsb.getFolder("sdk-test/folder");

Result

type Folder = {
  id: string;
  name: string;
  path: string;
  project: string;
  parentFolder?: string;
  createdAt: string;
  updatedAt: string;
  stats?: {
    documents: number;
    folders: number;
  };
};

getFolderWithStats()

Same as getFolder but also fills in stats (how many documents and folders are inside).

const folder = await jsb.getFolderWithStats("sdk-test/folder");

console.log(folder.stats) // { documents: 2, folders: 0 }

createFolder()

Create a new folder in a project. folder is optional, use it to nest inside another folder.

const folder = await jsb.createFolder({
  name: "folder",
  project: "sdk-test"
});

createFolderIfNotExists()

Same as createFolder, but if the folder already exists it is fetched and returned instead of throwing.

const folder = await jsb.createFolderIfNotExists({
  name: "folder",
  project: "sdk-test"
});

// when it already existed
folder.exists // true

Uploading Files

Upload a json file straight from your file system. This is only available in Node.js through JsonBankNode.

Note: Import the node version to get uploadDocument:
const { JsonBankNode } = require("jsonbank/node")

uploadDocument()

Reads a file from disk and creates a document from it. name and folder are optional, name defaults to the file name.

Code

const {JsonBankNode} = require("jsonbank/node")

const jsb = new JsonBankNode({
  keys: {
    pub: 'JSB_PUBLIC_KEY',
    prv: 'JSB_PRIVATE_KEY',
  }
});
await jsb.authenticate();

const doc = await jsb.uploadDocument({
  file: __dirname + "/upload.json",
  project: "sdk-test",
  folder: "folder", // optional
  name: "upload"    // optional
});

Result

type NewDocument = {
  id: string;
  name: string;
  path: string;
  project: string;
  createdAt: string;
};

Error Handling

Methods throw a JSB_Error when something goes wrong. It is a normal Error with an extra code you can check.

try {
  await jsb.createFolder({ name: "folder", project: "sdk-test" });
} catch (e) {
  // e is a JSB_Error
  if (e.code === "name.exists") {
    // folder already exists, ignore it or fetch it instead
  } else {
    throw e;
  }
}

Common error codes:

• notFound — the document or folder does not exist.
• name.exists — a document or folder with that name already exists.

Note: Some methods don't throw, they return a value instead: hasOwnDocument() returns false, deleteDocument() returns { deleted: false }, and the ...IfNotExists() methods return the existing item with exists: true.

Next steps

• Concepts — projects, paths, public vs private, and the key model.
• Webhooks — get notified when your documents change.
• Browse the other SDKs