bertha-client

bertha-client

A client library for fetching data from Bertha. For use in Node and the browser.

Why use this instead of fetching Bertha URLs with fetch or axios?

• takes care of the URL syntax
• gives more helpful error messages when things go wrong
• provides an easy way to transform sheets into objects

Installation

• yarn add bertha-client or npm install bertha-client

Browser: Use Browserify or Rollup. Requires window.fetch, so make sure this is polyfilled.

Node: Just require or import as usual. No need to polyfill anything – the Node version of bertha-client uses node-fetch without modifying the global scope.

Usage

import * as bertha from 'bertha-client'; // or const bertha = require('bertha-client');

bertha.get(spreadsheetKey, ['someSheet', 'anotherSheet|object']).then((data) => {
  console.log(data);
  // { someSheet: [...], anotherSheet: [...] }
});

API

bertha.get(spreadsheetKey, sheetNames, [options])

Fetches the sheet and returns a promise for the response data.

spreadsheetKey

String (required). A valid Google spreadsheet key, or a full Google Spreadsheet URL or Bertha URL.

sheetNames

Array of strings (required). The names of the sheets you want to get. A sheet name may be appended with |object to apply the "object" transformation.

// example
const sheetNames = [
  'polls',
  'authors',
  'copy|object', // applies the "object" transformation
]

options

Plain object (optional).

• republish (default: false) – set to true if you want Bertha to trigger a republish.
• query (default: undefined) – an optional object of {[name]: value} to append to the URL as query parameters.

bertha.createURL(spreadsheetKey, sheetNames, [options])

Identical API to bertha.get(), but simply returns a URL string.

bertha.parseKey(url, [silent])

Takes any valid Google Sheets URL or Bertha URL and returns a plain spreadsheet key. If the string you pass is already a plain key, it returns it unchanged.

If you set silent to true, invalid input will result in the function returning null instead of throwing an error.

bertha.domains

An array of known Bertha domains.

Response data

The data from bertha.get() is always returned as a plain JavaScript object (even if there is only one sheet). The key names correspond with the sheet names.

The |object transformation

If you append a sheet name with |object, that sheet will be transformed into a plain object (instead of an array), using the sheet's name and value columns as key paths and values, respectively. Any other columns are discarded.

Example spreadsheet:

name	value
foo	hiya
bar	123
someone.age	50
someone.name.first	Bob
someone.name.last	Hoskins
someone.name.last	y

// result of "|object" transform
{
  foo: 'hiya',
  bar: 123,
  someone: {
    age: 50,
    name: {
      first: 'Bob',
      last: 'Hoskins',
    }
  },
}

NB. the Bertha server automatically converts certain values ("y" or "yes" becomes true etc.) – see Bertha's docs. This conversion is not controlled by bertha-client – you'll need to specify a non-default column transform such as ..str if you want to control it.

Development

Local setup

Recommended approach:

• Clone this repo and run yarn.
• Run yarn run build -- --watch – this will compile files continually from src to dist using Babel.
• In another terminal, run yarn run ava -- --watch to run ava continually against files in dist.

Publishing to npm

This module is automatically published to npm via CircleCI whenever the master branch contains a higher version string than the latest published version.

To publish a new version:

• yarn version (will prompt you to enter a new version)
• git push && git push --tags

Changelog

[3.0.0] – 2017-06-07

Changed

• The object transform no longer coerces values to strings. So you can use Bertha's magic values like "y" (which becomes true), or specify your own column transform. This is a small but breaking change, hence the major version bump.