JavaScript SDK

Our JavaScript SDK is a much more convenient way to interact with the REST API. We designed it so you can utilize newer ES syntaxes such as async/await and generator. It is meant to run on web-based notebook such as ObservableHQ so it only run in the browser for now but we will add Node support in the future if more people need it.

Installation

is very straight forward...

Simply install it from npm:

npm install wrgl-sdk

and import in your project

import { Client } from "wrgl-sdk";

Cross Origin

Our API don't allow cross-origin requests by default. You need to manually add the origin you will make request from at cross origin settings page.

Authentication

You need to authenticate with API key to make modifications. You can get one at API key settings page. Note that API keys do not expire on their own (but you can remove them any time) and allow you to do everything so keep them a secret!

Example:

const client = new Client("<your API key>");

List repositories

There are 2 main methods to iterate over repositories. If you are comfortable using async generator then genRepo is the way to go. Otherwise use eachRepo as it doesn't use generator.

genRepo

Create an async generator to iterate over repositories. Yielding repo object each time.

Parameters Type Description
username string Required. Username of repo owner.
prefix string Optional. If given, only yield repo with name begin with this prefix.

eachRepo

Iterate over repositories using callback. Returns a promise that will resolve when there's nothing left.

Parameters Type Description
username string Username of repo owner.
prefix string If not empty, only iterate over repos with name that has this prefix.
callback function Called for each repository. Receive a repo object as argument. If this function return false then iteration is stopped.

Repo object

Fields Type Description
name string The repo name. Can only consist of lowercase alphanumeric characters, hyphen and underscore. It also must begin with an alphabet letter and is at least 2 characters long.
hash string Its latest commit hash. Use this to access the latest commit.
updateTime string Timestamp of latest commit. e.g. 2020-12-31T23:59:60Z
isPublic boolean Indicate whether this repo and all of its content is publicly accessible.
size number Total size in bytes of this repo.

Iterate over repos with async generator:

for await (let repo of client.genRepo(username)) {
  // repo object has the same properties as JSON payload
  ...
}

Iterate with eachRepo function:

await client.eachRepo(username, "", (repo) => {
  // do something with repo
  ...
});

Iterate over repos with prefix "em":

for await (let repo of client.genRepo(username, "em")) {
  ...
}
// or if you don't like using async generator
await client.eachRepo(username, "em", (repo) => {
  ...
});

Create commit

commit

Create a new commit. Returns a promise that will resolve with a commit result object.

Parameters Type Description
username string Username of repo owner.
reponame string Name of repository. If it's a new name then a new repo is created. Otherwise the commit is appended to existing repo.
csvFile File The CSV file to be uploaded.
primaryKey array of strings List of columns included in primary key. Note that the order of these columns matters. A different order mean a completely different primary key. If left empty then all columns are included in the primary key.

Commit result object

Fields Type Description
hash string The commit hash. Can be used to refer to this specific commit in other operations.
contentHash string Hash of commit's content - the CSV.

Example:

const { hash } = await client.commit(
  "johndoe",        // username
  "products",       // reponame
  csvFile,
  ["product_id"],   // primaryKey
  "initial commit"  // message
);

List commits

You can iterate over commits with 2 main methods. genCommit when you want to use async generator. eachCommit if you prefer callback.

genCommit

Create an async generator that iterate over commits, each time yielding a commit object.

Parameters Type Description
username string Username of repo owner.
reponame string Name of repository.

eachCommit

Iterate over commits using callback. Returns a promise that will resolve when there's nothing left.

Parameters Type Description
username string Username of repo owner.
reponame string Name of repository.
callback function Called for each commit. Receive a commit object as argument. If this function return false then iteration is stopped.

Iterate with async generator:

for await (let commit of client.genCommit(username, reponame)) {
  ...
}

Iterate with callback:

await client.eachCommit(username, reponame, (commit) => {
  ...
})

Get latest commit

getLatestCommit

Get the latest commit from a repository. Returns a promise that will resolve with a commit object.

Parameters Type Description
username string Username of repo owner.
reponame string Name of repository.

Commit object

Fields Type Description
hash string The commit hash.
message string Commit's purpose on plain English.
commitTime string Commit's timestamp.
prevCommitHash string Hash of the previous commit. Empty if this is the first commit in repo.
contentHash string Hash of underlying CSV.
table table object Contains some information about the underlying CSV.
authorId string Commit author id.
authorUsername string Commit author username.
authorAvatarUrl string Commit author avatar url.

Table object

Fields Type Description
columns array of strings List of all column names.
numRows number Number of rows in CSV. Note that rows with the same primary key are counted as 1.
primaryKey array of strings List of all columns included in primary key.

Example:

const latestCommit = await client.getLatestCommit(
  username,
  reponame
);

Get commit with hash

getCommit

Get a commit with specified hash from a repository. Returns a promise that will resolve with a commit object.

Parameters Type Description
username string Username of repo owner.
reponame string Name of repository.
hash string Hash of commit.

Example:

const commit = await client.getCommit(
  username,
  reponame,
  hash
);

Download CSV

csvUrl

Returns a download link for the CSV.

Parameters Type Description
username string Username of repo owner.
reponame string Name of repository.
hash string Commit hash

csvBlob

Download the CSV as a blob object.

Parameters Type Description
username string Username of repo owner.
reponame string Name of repository.
hash string Commit hash

Get a download-ready link for CSV:

const url = client.csvUrl(username, reponame, commitHash).toString()

Note that unless the repo is public this link is still cookie-protected so only logged-in user can use it.

To download the CSV as blob object:

const blob = await client.csvBlob(username, reponame, commitHash);

Publish repository

When you publish a repository all of its commits become public accessible. On free plan, repos are all publ. Private repo is only for paid plans.

publishRepo

Publish a repository.

Parameters Type Description
username string Username of repo owner.
reponame string Name of repository.

unpublishRepo

Make a repository private.

Parameters Type Description
username string Username of repo owner.
reponame string Name of repository.

Publish a repo:

await client.publishRepo(username, reponame);

Unpublish a repo:

await client.unpublishRepo(username, reponame);