README.md

Dropbox Client

Dropbox client library for Buttercup

About

Dropbox is an integral part of the Buttercup platform as it's used by a huge amount of users to store all kinds of data - including Buttercup vault files. Having a functional, portable and reliable Dropbox client interface is critical to the platform's stability, and currently the official Dropbox SDK is lacking in terms of quality and stability.

This library is a barebones HTTP client that makes requests directly to Dropbox's HTTP API using a token (handled externally - this library will not be responsible for fetching them). The result is a tiny, portable script that is reliable and simple to understand. It uses fetch (cross-fetch) to perform requests, which will obviously work in a reproducible fassion across environments.

Installation

Simply run npm install @buttercup/dropbox-client --save to install.

The latest version (v2) requires an ESM environment to run. It is not available to standard CommonJS projects.

Usage

Authorisation

You can generate Dropbox authorisation URLs by using generateAuthorisationURL:

import { generateAuthorisationURL } from "@buttercup/dropbox-client";

const url = generateAuthorisationURL("client-id", "https://redir.example.com");
// open `url`

Client

Use the DropboxClient class to create a client interface:

import { generateAuthorisationURL } from "@buttercup/dropbox-client";

const client = new DropboxClient("my-token");

You can then use the client adapter to make requests like for directory contents:

client
    .getDirectoryContents("/Documents")
    .then(contents => {
        // [ {
        //     name: "My directory",
        //     path: "/Documents/My directory",
        //     type: "directory"
        // }, {
        //     name: "results.pdf",
        //     path: "/Documents/results.pdf",
        //     type: "file"
        // } ]
    });

You can also read and write files using getFileContents and putFileContents, respectively.

Compatibility Mode

You can enable compatibility mode for browser-based environments where CORS may break requests:

const client = new DropboxClient("my-token", { compat: true });

In some browser environments the "CORS hack" Content-Type header can fail, so this can be disabled by specifying false for the compatCorsHack property:

const client = new DropboxClient("my-token", {
    compat: true,
    compatCorsHack: false
});

Custom Headers

You can provide custom headers to all the requests the client makes by specifying the headers option:

const client = new DropboxClient("my-token", {
    headers: {
        // Disable the cache (works/necessary in some environments)
        "Cache-Control": "no-cache, no-store, max-age=0"
    }
});

Fs

An fs-like interface is also available:

import { generateAuthorisationURL } from "@buttercup/dropbox-client";

const client = new DropboxClient("my-token");

client.fs.readdir("/photos", (err, items) => {
    // array of file names
});

Error Handling

Errors while performing requests against the Dropbox API will be thrown wrapped in a Layerr error instance. It provides some extra properties with each error:

import { Layerr } from "layerr";

// ...

client.getDirectoryContents("/").catch((err) => {
    const {
        status,
        statusText,
        url
    } = Layerr.info(err);

    if (status === 403) {
        // ...
    }
});